Realtime | ElevenLabs Documentation

Realtime speech-to-text transcription service. This WebSocket API enables streaming audio input and receiving transcription results.

Event Flow

Audio chunks are sent as input_audio_chunk messages
Transcription results are streamed back as partial_transcript (interim) and committed_transcript (stable/final for that segment)
Supports manual commit or VAD-based automatic commit strategies

Authentication is done either by providing a valid API key in the xi-api-key header or by providing a valid token in the token query parameter. Tokens can be generated from the single use token endpoint. Use tokens if you want to transcribe audio from the client side.

Realtime speech-to-text transcription service. This WebSocket API enables streaming audio input and receiving transcription results. ## Event Flow - Audio chunks are sent as `input_audio_chunk` messages - Transcription results are streamed back as `partial_transcript` (interim) and `committed_transcript` (stable/final for that segment) - Supports manual commit or VAD-based automatic commit strategies Authentication is done either by providing a valid API key in the `xi-api-key` header or by providing a valid token in the `token` query parameter. Tokens can be generated from the [single use token endpoint](/docs/api-reference/tokens/create). Use tokens if you want to transcribe audio from the client side.

Handshake

WSS

/v1/speech-to-text/realtime

Headers

xi-api-keystringOptional

Query parameters

model_idanyRequired

The ID of the model to use for speech-to-text transcription.

tokenanyOptional

Single use token for authentication. Only used when initiating a session from the client. If provided, xi-api-key is no longer required for authentication.

audio_formatanyOptional

The encoding format of the audio. Supported formats: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, ulaw_8000.

language_codeanyOptional

An ISO-639-1 or ISO-639-3 language_code corresponding to the language of the audio file. Can sometimes improve transcription performance if known beforehand. Defaults to null, in this case the language is predicted automatically.

secondary_languagesanyOptional

Additional ISO-639-1 or ISO-639-3 language codes that may be present in the audio. Providing them makes language identification more reliable by only focusing on a certain set of languages. Each code is validated the same way as language_code.

commit_strategyanyOptional

Commit strategy for speech segmentation. 'manual' requires explicit commits, 'vad' automatically segments speech using silence detection.

vad_thresholdanyOptional

VAD sensitivity threshold for detecting speech activity. Lower values are more sensitive to speech.

vad_silence_threshold_secsanyOptional

Duration of silence in seconds required to trigger a commit when VAD commit strategy is enabled. Longer values result in fewer commits but longer segments.

min_speech_duration_msanyOptional

Minimum duration of speech in milliseconds required to be considered valid speech by VAD.

min_silence_duration_msanyOptional

Minimum duration of silence in milliseconds required to be considered a speech break by VAD.

include_timestampsanyOptional

Enable word/character-level timestamps in a delayed committed_transcript_with_timestamps message. When enabled, you’ll receive an additional message with timestamps after each commit. Default: false.

include_language_detectionanyOptional

Enable language detection in a delayed committed_transcript_with_timestamps message. When enabled, you’ll receive an additional message with detected language_code after each commit. Default: false.

keytermsanyOptional

List of keyterms to bias the model towards. Maximum 50 keyterms. Adds a 20% premium to the base transcription cost.

no_verbatimanyOptional

If true, removes filler words, false starts and disfluencies from the transcript.

entity_detectionanyOptional

Detect entities on committed transcripts. Can be 'all', a single entity type or category, or a list of types/categories ('pii', 'phi', 'pci', 'other', 'offensive_language'). When enabled, detected entities are delivered in a separate 'committed_transcript_entities' event with their text, type, and character positions.

filter_background_audioanyOptional

Enable background speech filtering to reduce false activations from nearby conversations and ambient noise. When enabled without an explicit vad_threshold, a lower default threshold is applied. Cannot be combined with include_timestamps.

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

inputAudioChunkobjectRequired

Audio data chunk sent from client to server for transcription.

Receive

sessionStartedobjectRequired

Sent when the transcription session is successfully started.

partialTranscriptobjectRequired

Interim transcription result that may change.

committedTranscriptobjectRequired

Committed transcription result that will not change.

committedTranscriptWithTimestampsobjectRequired

Committed transcription result with word-level timestamps.

committedTranscriptEntitiesobjectRequired

Detected entities for a committed transcript. Only sent when the entity_detection query parameter is set.

Scribe WarningobjectRequired

Non-fatal notice. Sent after session_started when enable_logging=false was requested but zero retention mode was not applied; the session continues and is still logged.

scribeErrorobjectRequired

Error event during transcription.

scribeAuthErrorobjectRequired

Authentication error during transcription session.

scribeQuotaExceededErrorobjectRequired

Quota exceeded error during transcription session.

scribeThrottledErrorobjectRequired

Throttled error during transcription session.

scribeUnacceptedTermsErrorobjectRequired

Unaccepted terms error during transcription session.

scribeRateLimitedErrorobjectRequired

Rate limited error during transcription session.

scribeQueueOverflowErrorobjectRequired

Queue overflow error during transcription session.

scribeResourceExhaustedErrorobjectRequired

Resource exhausted error during transcription session.

scribeSessionTimeLimitExceededErrorobjectRequired

Session time limit exceeded error during transcription session.

scribeInputErrorobjectRequired

Input error during transcription session.

Scribe Invalid Request ErrorobjectRequired

The connection parameters were rejected; the session is closed afterwards.

scribeChunkSizeExceededErrorobjectRequired

Chunk size exceeded error during transcription session.

scribeInsufficientAudioActivityErrorobjectRequired

Insufficient audio activity error during transcription session.

scribeTranscriberErrorobjectRequired

Transcriber error during transcription session.

Realtime speech-to-text transcription service. This WebSocket API enables streaming audio input and receiving transcription results.

Event Flow

Audio chunks are sent as input_audio_chunk messages
Transcription results are streamed back as partial_transcript (interim) and committed_transcript (stable/final for that segment)
Supports manual commit or VAD-based automatic commit strategies

Headers

xi-api-keystringOptional

Query parameters

model_idanyRequired

The ID of the model to use for speech-to-text transcription.

tokenanyOptional

Single use token for authentication. Only used when initiating a session from the client. If provided, xi-api-key is no longer required for authentication.

audio_formatanyOptional

The encoding format of the audio. Supported formats: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, ulaw_8000.

language_codeanyOptional

secondary_languagesanyOptional

commit_strategyanyOptional

Commit strategy for speech segmentation. 'manual' requires explicit commits, 'vad' automatically segments speech using silence detection.

vad_thresholdanyOptional

VAD sensitivity threshold for detecting speech activity. Lower values are more sensitive to speech.

vad_silence_threshold_secsanyOptional

Duration of silence in seconds required to trigger a commit when VAD commit strategy is enabled. Longer values result in fewer commits but longer segments.

min_speech_duration_msanyOptional

Minimum duration of speech in milliseconds required to be considered valid speech by VAD.

min_silence_duration_msanyOptional

Minimum duration of silence in milliseconds required to be considered a speech break by VAD.

include_timestampsanyOptional

include_language_detectionanyOptional

keytermsanyOptional

List of keyterms to bias the model towards. Maximum 50 keyterms. Adds a 20% premium to the base transcription cost.

no_verbatimanyOptional

If true, removes filler words, false starts and disfluencies from the transcript.

entity_detectionanyOptional

Detect entities on committed transcripts. Can be ‘all’, a single entity type or category, or a list of types/categories (‘pii’, ‘phi’, ‘pci’, ‘other’, ‘offensive_language’). When enabled, detected entities are delivered in a separate ‘committed_transcript_entities’ event with their text, type, and character positions.

filter_background_audioanyOptional

enable_logginganyOptional

Audio data chunk sent from client to server for transcription.

Sent when the transcription session is successfully started.

Interim transcription result that may change.

Committed transcription result that will not change.

Committed transcription result with word-level timestamps.

Detected entities for a committed transcript. Only sent when the entity_detection query parameter is set.

Non-fatal notice. Sent after session_started when enable_logging=false was requested but zero retention mode was not applied; the session continues and is still logged.

Error event during transcription.

Authentication error during transcription session.

Quota exceeded error during transcription session.

Throttled error during transcription session.

Unaccepted terms error during transcription session.

Rate limited error during transcription session.

Queue overflow error during transcription session.

Resource exhausted error during transcription session.

Session time limit exceeded error during transcription session.

Input error during transcription session.

The connection parameters were rejected; the session is closed afterwards.

Chunk size exceeded error during transcription session.

Insufficient audio activity error during transcription session.

Transcriber error during transcription session.

URL	wss://api.elevenlabs.io/v1/speech-to-text/realtime
Method	GET
Status	101 Switching Protocols

Event Flow

HandshakeTry it

Headers

Query parameters

Send

Receive

Event Flow

HandshakeTry it

Headers

Query parameters

Send

Receive

Handshake

Handshake