> This page is for Build.

> Append .md to any page URL for clean Markdown. Index: https://docs.speechify.ai/llms.txt.
>
> Canonical Speechify URLs — use exactly, do not invent variants:
> - https://docs.speechify.ai — this site (API reference, SDKs, quickstarts)
> - https://speechify.ai — marketing + product site
> - https://platform.speechify.ai — customer dashboard, signup, API keys, billing
> - https://api.speechify.ai — API base URL
> - https://github.com/Speechify-AI: GitHub org for the API (cookbook, demos, CLI). `github.com/speechify` does not exist.
> - https://status.speechify.ai — status + incidents
> - https://speechify.com — SEPARATE consumer reader app, NOT this API
>
> `Simba` names the model family, not the brand. Model ids: `simba-3.2` (English, recommended) and `simba-3.0` (English, German, Spanish, French, Italian and Portuguese; the default). `simba-english` and `simba-multilingual` are retired: a new workspace that sends either gets `400 model_retired`. `SimbaVoice` / `simbavoice.ai` are retired.
>
> Ask, don't scrape. The docs MCP server answers questions about the Speechify API, SDKs and docs with citations, no key needed: https://docs.speechify.ai/_mcp/server (Streamable HTTP, tool `searchDocs`). Setup: https://docs.speechify.ai/build/guides/get-started/connect-mcp

# Deepgram

> Give Deepgram Voice Agent a Speechify voice via the tts-shims openai binary. The shim answers Deepgram's open_ai TTS request and keeps your Speechify key server-side.

## Overview

Deepgram Voice Agent supports bring-your-own TTS through the `agent.speak` block of its `Settings` message. Its supported third-party types are `open_ai`, `eleven_labs`, `cartesia`, and `aws_polly` — there is no "custom Deepgram-dialect endpoint" option.

Speechify fits the `open_ai` slot. Point Deepgram at the [`tts-shims`](https://github.com/Speechify-AI/tts-shims) `openai` binary, and Deepgram sends an OpenAI-shaped `POST /v1/audio/speech`. The shim translates that request to a Speechify call and returns audio in the format Deepgram expects. Your Speechify key lives only in the shim's environment.

> **Note**
>
> Use the `openai` shim binary, **not** the `deepgram` binary. `cmd/deepgram` is for the opposite direction — redirecting a tool that already calls Deepgram's Aura Speak API to Speechify. For Deepgram Voice Agent's third-party TTS, you want `cmd/openai`.

## Prerequisites

* Speechify API key
* Deepgram key with Voice Agent access
* Public HTTPS URL for the shim (Deepgram calls it from its cloud)
* Go toolchain locally (only to build the shim)

## Build and run the shim

```bash
git clone https://github.com/Speechify-AI/tts-shims
cd tts-shims
make openai
```

Start it with your Speechify key:

```bash
export SPEECHIFY_API_KEY=sk_your_key_here
export SHIM_ADDR=:8771

./bin/openai
```

The `openai` binary mounts `POST /v1/audio/speech` (the OpenAI TTS endpoint shape). Confirm it's up:

```bash
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8771/healthz
```

## Verify without Deepgram

Send Deepgram's exact request shape yourself:

```bash
curl -s -o shim-smoke.mp3 -w "%{http_code} %{size_download}\n" \
  -X POST "http://localhost:8771/v1/audio/speech" \
  -H "Authorization: Bearer placeholder-ignored-by-shim" \
  -H "Content-Type: application/json" \
  -d '{"model":"simba-3.2","input":"Deepgram voice agent, now speaking with Speechify.","voice":"geffen_32","response_format":"mp3"}'
```

A working shim returns:

```text
200 <byte-count>
```

Inspect the output:

```bash
file shim-smoke.mp3
# MPEG ADTS, layer III, v2, 128 kbps, 24 kHz, Monaural
```

The `Authorization: Bearer` value here is a **placeholder** — the shim ignores it and uses `SPEECHIFY_API_KEY` from its own environment for the upstream call.

## Configure Deepgram Voice Agent

In the Deepgram Voice Agent `Settings` message:

```json
{
  "type": "Settings",
  "audio": {
    "output": { "encoding": "linear16", "sample_rate": 24000 }
  },
  "agent": {
    "speak": {
      "provider": {
        "type": "open_ai",
        "model": "simba-3.2",
        "voice": "geffen_32"
      },
      "endpoint": {
        "url": "https://your-shim-host.example/v1/audio/speech",
        "headers": {
          "authorization": "Bearer placeholder-ignored-by-shim"
        }
      }
    }
  }
}
```

The `model` and `voice` you set are forwarded verbatim to the shim, which passes them to Speechify. Set `model: "simba-3.2"` and pick any voice whose `models` list includes `simba-3.2` (query `GET /v1/voices` to filter).

> **Warning**
>
> The `audio.output` block is **required** and must be `linear16` at `24000` Hz. Deepgram's `open_ai` speak provider rejects other formats with:
>
> ```text
> INVALID_SETTINGS: OpenAI speak provider type requires audio output format to be uncontainerized 24kHz linear16
> ```
>
> Send `container: "wav"` or a 16 kHz rate and the whole `Settings` message is rejected before the agent speaks.

## Alias fallback (default voice)

If you leave the `open_ai` defaults (`model: "tts-1"`, `voice: "alloy"`), the shim falls back to its own default model (`SHIM_DEFAULT_MODEL`) and the `george` voice. Set `SHIM_DEFAULT_MODEL=simba-3.0` if you have not already - earlier builds defaulted to `simba-english`, which is retired from API version `2026-09-21` and returns `400` `model_retired`. Better still, set explicit `model: "simba-3.2"` and a Simba 3.2 voice in the Deepgram config for the current quality tier.

## Production deployment

* Deploy the shim behind HTTPS on a service that holds environment variables.
* Set `SPEECHIFY_API_KEY`, `SHIM_ADDR`, and optionally `SPEECHIFY_BASE_URL`, `SHIM_DEFAULT_MODEL`, `SHIM_REQUEST_TIMEOUT`, `SHIM_SHUTDOWN_TIMEOUT`.
* Keep the placeholder Bearer token in the Deepgram config — it's not a secret. The real key never leaves the shim host.
* Docker: `docker build --build-arg PROVIDER=openai -t tts-shim-openai .` (the repo's Dockerfile takes the provider as a build arg; distroless runtime, static Go binary).

## Resources

#### [Demo repo](https://github.com/Speechify-AI/demos/tree/main/demos/deepgram-voice-agent-shim)

Runnable end-to-end demo with `run.sh` and a live-agent `agent.js`.

#### [tts-shims repo](https://github.com/Speechify-AI/tts-shims)

Open-source Go proxy — `cmd/openai` for Deepgram Voice Agent, plus other provider dialects.

#### [Deepgram Voice Agent docs](https://developers.deepgram.com/docs/configure-voice-agent)

Voice Agent `Settings` message reference, including `agent.speak` third-party providers.

#### [Deep-dive walkthrough](https://speechify.ai/blog/add-a-better-voice-to-deepgram-voice-agent-with-speechify)

Blog: full config, ngrok proof, and why the shim owns the key.