Turn-based speech (Flux TTS)
Streaming, turn-based text-to-speech (Flux TTS) built for voice-agent pipelines. Stream LLM tokens in, speak them to the user, and report per-turn billing and timing.
HandshakeTry it
Authentication
Use Authorization: Token <API_KEY>
Example: Authorization: Token 12345abcdef
Use Authorization: Bearer <JWT>
Example: Authorization: Bearer eyJhbGciOiJ...
Headers
Use your API key or a temporary token for authentication via the Authorization header. In client-side environments where custom headers are not supported, use the Sec-WebSocket-Protocol header instead.
Example: Authorization: Token %DEEPGRAM_API_KEY% or Authorization: Bearer %DEEPGRAM_TOKEN%
Query parameters
The Flux TTS model used to synthesize speech. Required on every connection. Model strings follow the format flux-{voice}-{language} (e.g. flux-alexis-en). An Aura model string is rejected on /v2/speak; use /v1/speak for Aura voices.
Encoding of the raw output audio. The streaming WebSocket emits raw (non-containerized) audio, so only streaming-compatible encodings are supported. Compressed and containerized encodings (mp3, opus, flac, aac) are available on the batch REST transport only.
Output sample rate in Hz. With linear16, valid values are 8000, 16000, 24000, 32000, 44100, and 48000. With mulaw or alaw, valid values are 8000 and 16000. Defaults to the model’s native sample rate.
Speech-rate multiplier. 1.0 is the model’s nominal rate; lower is slower. Accepted values run 0.5 to 1.5 in 0.05 increments. A value outside that range is rejected with SPEED_OUT_OF_RANGE; a value inside it but off the 0.05 increment with SPEED_INCREMENT_INVALID. Models and languages without runtime speed control reject any value with SPEED_NOT_SUPPORTED. A speed other than 1.0 cannot be combined with inline pronunciation controls; see Speed, Pause, Pronunciation.
Expressive range of the generated speech, on a calm-to-animated axis. Accepted values: -2, -1, 0, 1, 2. 0 (the default) is the voice’s tuned delivery and the production-validated setting, with -2 the calm end of the range and 2 the animated end. Supported on all Flux voices. Fixed for the connection — not settable via Configure. Beta: behavior may change in future model versions, and non-default values increase the risk of hallucinations and pronunciation errors; audition before shipping. An invalid value fails the connection with a 400 — EXPRESSIVITY_OUT_OF_RANGE for a value outside the range, EXPRESSIVITY_INCREMENT_INVALID for a fractional value. See Expressivity.
Normalizes the loudness of the generated speech to a consistent level across voices and turns. On by default; set to false to opt out. Peak limiting is applied either way.
Opts out requests from the Deepgram Model Improvement Program. Refer to our Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip
Send
Send text to be synthesized into the active turn. For English, German, Dutch, French, Hindi, Italian, Japanese, Portuguese, Russian and Spanish, the server applies text normalization (numbers, dates, abbreviations) before synthesis; the other languages are in Early Access without it, so write numbers and dates out in words. It tracks the active turn internally and assigns a speech_id; clients do not specify one.
End the active turn. The server drains the buffer, generates the remaining audio, and reports the turn with a SpeechMetadata event.
Report that the user barged in. The server stops active audio generation, discards any buffered text pending generation, and replies with SpeechInterrupted once the model confirms the cancelled turn has drained.
Update synthesis configuration mid-session without reconnecting. Omitted fields keep their current value, and a Configure naming no field at all is accepted as a no-op. An accepted change takes effect at the next segment boundary, not mid-segment, so audio already generated is unaffected. Answered by exactly one of ConfigureSuccess or ConfigureFailure. A rejected Configure leaves the previous configuration in force.
Gracefully close the connection. The server drains all remaining audio (the active turn plus any turns still queued behind it), emits a final SessionMetadata, then closes the socket.
Receive
Sent immediately on a successful connection. Successor to the /v1/speak Metadata message.
Emitted at the start of each new turn, before audio streaming begins. Carries the server-assigned speech_id that identifies the turn. Fires once per turn, not on internal auto-flush boundaries.
Emitted at turn boundaries (manual Flush), after all audio for the turn has been sent. Reports billing and timing for the completed turn.
Sent in reply to an Interrupt, once synthesis has concluded and audio generation has stopped. Reports what the user heard, what they did not, and the billing and timing of the turn the interrupt landed in.
Immediate echo on receipt of a manual Flush, confirming the server received it before synthesis completes. Not emitted for internal auto-flush boundaries.
Sent when a Configure was accepted and applied. Echoes the configuration now in effect. A Configure that named no field is answered with an empty applied object.
Sent when a Configure was rejected. The stream is unaffected and the previous configuration stays in force. When the failure is tied to a specific field, field names it and value echoes the value that was rejected.
Informational message; synthesis continues and the connection is unaffected. Every warning carries a code and a human-readable description.
A fatal, server-originated error. Always followed by a WebSocket close. Codes use Deepgram’s DOMAIN-NNNN convention.