Text To Speech

Deepgram Text-to-Speech

Deepgram serves two text-to-speech families on separate endpoints, and the voices do not overlap. Aura voices run only on /v1/speak. Flux TTS voices run only on /v2/speak. /v2/speak is an additional endpoint. /v1/speak is unchanged and remains supported.

Pick the family first

Rule of thumb: Aura for one-shot and non-English, Flux TTS for voice agents. Flux TTS voices are English only today; for other languages use Aura-2.

First request: Aura over REST

curl --request POST \
  --url "https://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&container=wav" \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text": "Hello, how can I help you today?"}' \
  --output hello.wav \
  --fail-with-body --silent || echo "Request failed"

What to expect:

• A 2xx body is binary audio. Errors are JSON. Check the HTTP status before you parse.
• Options go on the query string. The JSON body carries only text.
• With no encoding, REST returns mp3. For WAV send encoding=linear16&container=wav. Other REST encodings: opus, flac, aac, mulaw, alaw, with container, bit_rate, sample_rate.
• If you omit model, /v1/speak uses aura-asteria-en, an Aura-1 voice. Always set model.
• Aura-2 speed accepts 0.7 to 1.5 and works for English and Spanish voices only.

Aura over WebSocket

Connect to wss://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&sample_rate=24000 with the same Authorization: Token header. Send JSON text frames: {"type":"Speak","text":"..."} to queue text, {"type":"Flush"} to force audio out, {"type":"Clear"} to drop the buffer, and {"type":"Close"} to end. Audio arrives as binary frames; Metadata, Flushed, Cleared, and Warning arrive as JSON. Send Flush when the LLM finishes a response. Flush is limited to 20 sends per 60 seconds. Streaming output is raw linear16 (default), mulaw, or alaw only.

Flux TTS for voice agents

Connect to wss://api.deepgram.com/v2/speak?model=flux-haley-en. model is required and must be a flux-* voice. There is no default, and an Aura string is rejected.

A session is a sequence of turns. Stream tokens in, then end the turn:

{"type": "Speak", "text": "Sure, I can "}
{"type": "Speak", "text": "help you cancel your subscription."}
{"type": "Flush"}

• Audio starts streaming before you Flush. Flush ends the turn; the server then sends Flushed and SpeechMetadata with billing and timing. Treat SpeechMetadata as the end of the turn; Flushed arrives earlier.
• The server assigns speech_id per turn in SpeechStarted and SpeechMetadata. Never send one.
• On barge-in, stop local playback first, then send {"type":"Interrupt","playback_offset":{"type":"time_ms","value":2340}}. SpeechInterrupted returns text_spoken and text_remaining; feed text_spoken back into the LLM context. Without a playback_offset the split is omitted.
• {"type":"Configure","speed":1.15} changes speed mid-session. speed runs 0.5 to 1.5 in 0.05 increments, default 1.0. 0.45 and 1.55 return 'speed' must be between 0.5 and 1.5, and 1.07 returns 'speed' must be provided in increments of 0.05. Errors: SPEED_OUT_OF_RANGE, SPEED_INCREMENT_INVALID, SPEED_NOT_SUPPORTED.
• expressivity runs -2 (calm) to 2 (animated), default 0. Values must be whole numbers; a fractional value returns EXPRESSIVITY_INCREMENT_INVALID and an out-of-range one EXPRESSIVITY_OUT_OF_RANGE. It is beta, fixed per connection (Configure cannot change it), and only 0 is validated for production.
• The socket emits raw linear16 (default), mulaw, or alaw. Batch-only parameters (container, bit_rate, callback, callback_method, priority) and any unknown parameter fail the connection.
• Idle sessions close after 60 seconds (NET-0004). Send a WebSocket Ping between quiet turns.
• Batch: POST https://api.deepgram.com/v2/speak?model=flux-haley-en with {"text": "..."} returns one audio response, mp3 by default, and accepts opus, flac, aac, container, bit_rate.
• SDKs: every Deepgram SDK except Go ships a Flux TTS client. Python, JavaScript, and Java name it ; .NET ships and ; Rust ships . In Go, use the WebSocket directly.

Voices

• Aura: aura-2-{voice}-{lang} in English, Spanish, German, French, Dutch, Italian, and Japanese, plus twelve Aura-1 English voices named aura-{voice}-en. Catalog: https://developers.deepgram.com/docs/tts-models (opens in a new tab)
• Flux TTS: flux-{voice}-en, English only, in American, British, Irish, Australian, Indian, Singaporean, and Filipino accents. Featured voices include flux-haley-en, flux-alexis-en, and flux-kit-en. Catalog: https://developers.deepgram.com/docs/flux-tts/voices (opens in a new tab)

Pricing

Text-to-speech is billed per 1,000 characters of input text, for Flux TTS, Aura-2, and Aura-1 alike. Rates differ by model and plan and change over time. Read them at https://deepgram.com/pricing (opens in a new tab); do not quote figures from memory.

Common mistakes

1. Wrong auth scheme. API keys go in Authorization: Token <key>. Bearer is only for the short-lived JWT from POST https://api.deepgram.com/v1/auth/grant. A key sent with Bearer returns 401.
2. Misreading a 403. The body {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."} comes back both for a model the project cannot use and for a misspelled model name. Before asking for access, check the name against the catalogs above and against GET https://api.deepgram.com/v1/models, whose tts list shows the models your key can use.
3. Parsing audio as JSON. Success bodies are bytes on both endpoints. Branch on status first.
4. Crossing the families. An Aura voice on /v2/speak and a Flux voice on /v1/speak both fail, and /v2/speak also rejects a missing model.
5. Asking a WebSocket for mp3. Streaming is raw audio on both endpoints. Use REST for compressed output.
6. Dropping the space between LLM generations on Flux TTS. Speak texts are concatenated verbatim, so "Hello world." then "How are you?" becomes "Hello world.How are you?". Insert a space when you stitch a reply, a tool result, and another reply. SSML is stripped with an INPUT_MARKUP_STRIPPED warning; send plain text.
7. Pointing a Voice Agent at api.deepgram.com. The Voice Agent API lives at wss://agent.deepgram.com and picks the TTS family from agent.speak.provider.version: v2 for Flux TTS, v1 for Aura. Omitting agent.speak gives Flux TTS with flux-kit-en.
8. Using Aura speed on a German, French, Dutch, Italian, or Japanese voice. Aura-2 speed control covers English and Spanish only.

Use a different skill when

• You need every parameter, enum, or message schema: api skill, file references/speak.md.
• You need a docs page you cannot name: docs skill.
• You want a runnable app: starters skill. Features are text-to-speech (Aura REST), live-text-to-speech (Aura WebSocket), and flux-tts (node, flask, fastapi, django, java only).
• You want a snippet under 50 lines: recipes skill. Recipes cover Aura on /v1/speak only; there are no Flux TTS recipes yet.
• You are wiring a third-party platform: examples skill (Aura today). For Twilio with Flux TTS, follow https://developers.deepgram.com/docs/twilio-and-deepgram-tts (opens in a new tab).
• You want the docs inside your coding tool: setup-mcp skill.
• You want idiomatic code in one language: the deepgram-{js,python,java,go,rust,dotnet}-text-to-speech skills from the SDK repositories (npx skills add deepgram/deepgram-python-sdk, and so on). Every SDK but Go carries a Flux TTS client; see the SDK note above for what each one calls it.
• You want Deepgram to run speech-to-text, the LLM, and TTS in one connection: voice-agent skill and deepgram-{lang}-voice-agent.
• You are transcribing rather than synthesizing: speech-to-text skill. Note that “Flux” names both a speech-to-text product on /v2/listen and this text-to-speech product on /v2/speak.

Sources

All pages fetched September 2026 as Markdown (append .md to any URL); index at https://developers.deepgram.com/llms.txt (opens in a new tab).

• Aura: https://developers.deepgram.com/docs/text-to-speech (opens in a new tab) https://developers.deepgram.com/docs/streaming-text-to-speech (opens in a new tab) https://developers.deepgram.com/docs/tts-models (opens in a new tab) https://developers.deepgram.com/docs/tts-voice-controls (opens in a new tab) https://developers.deepgram.com/docs/tts-encoding (opens in a new tab) https://developers.deepgram.com/docs/tts-media-output-settings