WebSocket | ElevenLabs Documentation

Stream expressive dialogue audio over a WebSocket by sending incremental text segments per registered voice.

The connection uses Eleven v3 dialogue models only (model_id must start with eleven_v3). The default model is eleven_v3_conversational.

Session setup

After connecting, the first JSON message must include voices (voice IDs to register for the session) and credentials if not already sent via headers or query string.
Optional voice_settings and pronunciation_dictionary_locators are only accepted on the first message.
For eleven_v3_conversational, only one voice ID may be registered. For eleven_v3, you may register up to 10 voices.

Streaming text

Send inputs: an array of { "text", "voice_id", "new_turn"? }. Text for the same turn is buffered until the server has enough context (at least ~40 characters and 8 words), then partial audio chunks are emitted.
Set new_turn to true (or switch voice_id) to finalize the current prosody segment and start a new speaker turn.

Control messages

flush: force generation of any buffered text without closing the socket.
close_socket: flush remaining audio, send a final message, and close the connection.
keep_alive: reset the 20 second receive timeout (no generation).

Authentication

Use the xi-api-key or Authorization header, single_use_token query parameter, or include xi_api_key, authorization, or single_use_token in the first message body (same pattern as Text to Speech WebSocket). Anonymous sessions are rejected.

For non-streaming dialogue over HTTP, see Create dialogue and Stream dialogue.

Stream expressive dialogue audio over a WebSocket by sending incremental text segments per registered voice. The connection uses Eleven v3 dialogue models only (`model_id` must start with `eleven_v3`). The default model is `eleven_v3_conversational`. ## Session setup - After connecting, the first JSON message **must** include `voices` (voice IDs to register for the session) and credentials if not already sent via headers or query string. - Optional `voice_settings` and `pronunciation_dictionary_locators` are only accepted on the first message. - For `eleven_v3_conversational`, only **one** voice ID may be registered. For `eleven_v3`, you may register up to **10** voices. ## Streaming text - Send `inputs`: an array of `{ "text", "voice_id", "new_turn"? }`. Text for the same turn is buffered until the server has enough context (at least ~40 characters and 8 words), then partial audio chunks are emitted. - Set `new_turn` to `true` (or switch `voice_id`) to finalize the current prosody segment and start a new speaker turn. ## Control messages - `flush`: force generation of any buffered text without closing the socket. - `close_socket`: flush remaining audio, send a final message, and close the connection. - `keep_alive`: reset the **20 second** receive timeout (no generation). ## Authentication Use the `xi-api-key` or `Authorization` header, `single_use_token` query parameter, or include `xi_api_key`, `authorization`, or `single_use_token` in the first message body (same pattern as [Text to Speech WebSocket](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-stream-input)). Anonymous sessions are rejected. For non-streaming dialogue over HTTP, see [Create dialogue](/docs/api-reference/text-to-dialogue/convert) and [Stream dialogue](/docs/api-reference/text-to-dialogue/stream).

Handshake

WSS

/v1/text-to-dialogue/stream-input

Headers

xi-api-keystringOptional

Query parameters

model_idanyOptional

Identifier of the model that will be used, you can query them using GET /v1/models. Must be a v3 model.

output_formatanyOptional

Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32.

language_codeanyOptional

Language code (ISO 639-1) used to enforce a language for the model and text normalization. If the model does not support the provided language code, it will be ignored. This parameter is not supported for multilingual_v2 models.

sync_alignmentanyOptional

When true, character timing from the model may be attached to audio chunks as alignment (snake_case field names).

apply_text_normalizationanyOptional

A string parameter to control text normalization.

seedanyOptional

If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed.

enable_logginganyOptional

When enable_logging is set to false zero retention mode will be used for the request. This will mean history features are unavailable for this request, including request stitching. Zero retention mode may only be used by enterprise customers.

Send

text_to_dialogue_websocket_clientobjectRequired

JSON text frame from client. The first frame must register voices; later frames stream inputs and control flags.

Receive

text_to_dialogue_websocket_audio_chunkobjectRequired

Partial audio for the current generation, base64-encoded using output_format.

text_to_dialogue_websocket_final_audio_for_turnobjectRequired

Sent after the final audio for a given turn has been sent. For streaming codecs (MP3, Opus, etc.), the persistent encoder buffers a small amount of audio across turn boundaries, so a few bytes belonging to the marked turn may arrive interleaved with the next turn's first audio chunk. Clients that need exact per-turn boundaries should request a PCM output format, which has no buffering.

text_to_dialogue_websocket_finalobjectRequired

Sent after close_socket once all audio has been flushed.

text_to_dialogue_websocket_errorobjectRequired

Error payload sent before the socket is closed with a WebSocket close code.

Stream expressive dialogue audio over a WebSocket by sending incremental text segments per registered voice.

The connection uses Eleven v3 dialogue models only (model_id must start with eleven_v3). The default model is eleven_v3_conversational.

Session setup

After connecting, the first JSON message must include voices (voice IDs to register for the session) and credentials if not already sent via headers or query string.
Optional voice_settings and pronunciation_dictionary_locators are only accepted on the first message.
For eleven_v3_conversational, only one voice ID may be registered. For eleven_v3, you may register up to 10 voices.

Streaming text

Send inputs: an array of { "text", "voice_id", "new_turn"? }. Text for the same turn is buffered until the server has enough context (at least ~40 characters and 8 words), then partial audio chunks are emitted.
Set new_turn to true (or switch voice_id) to finalize the current prosody segment and start a new speaker turn.

Control messages

flush: force generation of any buffered text without closing the socket.
close_socket: flush remaining audio, send a final message, and close the connection.
keep_alive: reset the 20 second receive timeout (no generation).

Authentication

For non-streaming dialogue over HTTP, see Create dialogue and Stream dialogue.

Headers

xi-api-keystringOptional

Query parameters

model_idanyOptional

Identifier of the model that will be used, you can query them using GET /v1/models. Must be a v3 model.

output_formatanyOptional

Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32.

language_codeanyOptional

sync_alignmentanyOptional

When true, character timing from the model may be attached to audio chunks as alignment (snake_case field names).

apply_text_normalizationanyOptional

A string parameter to control text normalization.

seedanyOptional

enable_logginganyOptional

JSON text frame from client. The first frame must register voices; later frames stream inputs and control flags.

Partial audio for the current generation, base64-encoded using output_format.

Sent after the final audio for a given turn has been sent. For streaming codecs (MP3, Opus, etc.), the persistent encoder buffers a small amount of audio across turn boundaries, so a few bytes belonging to the marked turn may arrive interleaved with the next turn’s first audio chunk. Clients that need exact per-turn boundaries should request a PCM output format, which has no buffering.

Sent after close_socket once all audio has been flushed.

Error payload sent before the socket is closed with a WebSocket close code.

Sent after the final audio for a given turn has been sent. For streaming codecs (MP3, Opus, etc.), the persistent encoder buffers a small amount of audio across turn boundaries, so a few bytes belonging to the marked turn may arrive interleaved with the next turn’s first audio chunk. Clients that need exact per-turn boundaries should request a PCM output format, which has no buffering.

URL	wss://api.elevenlabs.io/v1/text-to-dialogue/stream-input
Method	GET
Status	101 Switching Protocols

Session setup

Streaming text

Control messages

Authentication

HandshakeTry it

Headers

Query parameters

Send

Receive

Session setup

Streaming text

Control messages

Authentication

HandshakeTry it

Headers

Query parameters

Send

Receive

Handshake

Handshake