Skip to navigation
API ReferenceSpeech-to-text

Live audio

Transcribe audio and video using Deepgram’s speech-to-text WebSocket

HandshakeTry it

WSS
wss://api.deepgram.com/v1/listen

Authentication

AuthorizationToken

Use Authorization: Token <API_KEY> Example: Authorization: Token 12345abcdef

OR
AuthorizationBearer

Use Authorization: Bearer <JWT> Example: Authorization: Bearer eyJhbGciOiJ...

Headers

AuthorizationstringRequired

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

callbackanyOptional
URL to which we'll make the callback request
callback_methodenumOptionalDefaults to POST
HTTP method by which the callback request will be made
Allowed values:
channelsanyOptionalDefaults to 1
The number of channels in the submitted audio
detect_entitiesenumOptionalDefaults to false
Identifies and extracts key entities from content in submitted audio. Entities appear in final results. When enabled, Punctuation will also be enabled by default
Allowed values:
diarizeenumOptionalDefaults to falseDeprecated

Deprecated: use diarize_model instead. Recognize speaker changes. Each word in the transcript will be assigned a speaker number starting at 0.

Allowed values:
diarize_modelenumOptional

Select and enable a specific diarization model version. Specifying this parameter enables diarization and selects the model — you do not need to also set diarize=true. Supported values for streaming: v1, latest. The v2 value is not supported on streaming and returns a validation error.

Allowed values:
dictationenumOptionalDefaults to false
Identify and extract key entities from content in submitted audio
Allowed values:
encodingenumOptional
Specify the expected encoding of your submitted audio
endpointinganyOptionalDefaults to 10

Indicates how long Deepgram will wait to detect whether a speaker has finished speaking or pauses for a significant period of time. When set to a value, the streaming endpoint immediately finalizes the transcription for the processed time range and returns the transcript with a speech_final parameter set to true. Can also be set to false to disable endpointing

extraanyOptional

Arbitrary key-value pairs that are attached to the API response for usage in downstream processing

interim_resultsenumOptionalDefaults to false
Specifies whether the streaming endpoint should provide ongoing transcription updates as more audio is received. When set to true, the endpoint sends continuous updates, meaning transcription results may evolve over time
Allowed values:
keytermanyOptional

Key term prompting improves recognition of specialized terminology and brands. Only compatible with Nova-3.

keyterm accepts plain terms only. Unlike the legacy keywords feature, it does not support weights or intensifiers. Appending one (for example, keyterm=term:0.15) is not rejected—the weight is silently ignored and the entire value is treated as a literal keyterm.

To boost multiple separate keyterms, repeat the keyterm parameter (for example, keyterm=term1&keyterm=term2). To boost one multi-word phrase as a single keyterm, join the words with %20 or + (for example, keyterm=customer%20service). Do not separate keyterms with commas, semicolons, or line breaks.

keywordsanyOptional

Keywords can boost or suppress specialized terminology and brands. keywords is not supported with Nova-3 models; use keyterm instead.

languageanyOptionalDefaults to en

The BCP-47 language tag that hints at the primary spoken language. Depending on the Model you choose only certain languages are available

language_hintstring or list of stringsOptional

Biases language detection toward one or more languages on Nova-3 multilingual (model=nova-3&language=multi); ignored with any other language. Repeat the parameter to pass several codes, for example language_hint=en&language_hint=es. A code that is not in the Nova-3 multilingual list rejects the WebSocket connection with HTTP 400. See Nova-3 Language Prompting.

mip_opt_outanyOptionalDefaults to false

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

modelenumRequired
AI model to use for the transcription
multichannelenumOptionalDefaults to false
Transcribe each audio channel independently
Allowed values:
numeralsenumOptionalDefaults to false
Convert numbers from written format to numerical format
Allowed values:
profanity_filterenumOptionalDefaults to false

Profanity Filter looks for recognized profanity and converts it to the nearest recognized non-profane word or removes it from the transcript completely

Allowed values:
punctuateenumOptionalDefaults to false
Add punctuation and capitalization to the transcript
Allowed values:
redactenumOptionalDefaults to false
Redaction removes sensitive information from your transcripts
redact_usageenumOptionalDefaults to false

Replaces the values of user-supplied text parameters (keyterm, keywords, replace, search, and extra) with [REDACTED] in this request’s usage records. Does not affect transcription, the response, or tag. Independent of mip_opt_out. https://developers.deepgram.com/docs/redact-usage

Allowed values:
replaceanyOptional
Search for terms or phrases in submitted audio and replaces them
sample_rateanyOptional

Sample rate of submitted audio. Required (and only read) when a value is provided for encoding

searchanyOptional
Search for terms or phrases in submitted audio
smart_formatenumOptionalDefaults to false
Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability
Allowed values:
taganyOptional
Label your requests for the purpose of identification during usage reporting
utterance_end_msanyOptional

Indicates how long Deepgram will wait to send an UtteranceEnd message after a word has been transcribed. Use with interim_results

vad_eventsenumOptionalDefaults to false
Indicates that speech has started. You'll begin receiving Speech Started messages upon speech starting
Allowed values:
versionanyOptionalDefaults to latest
Version of an AI model to use

Send

ListenV1MediastringRequiredformat: "binary"
Audio data is transmitted as raw binary WebSocket messages
OR
ListenV1FinalizeobjectRequired
Control messages for managing the Speech to Text WebSocket connection
OR
ListenV1CloseStreamobjectRequired
Control messages for managing the Speech to Text WebSocket connection
OR
ListenV1KeepAliveobjectRequired
Control messages for managing the Speech to Text WebSocket connection
OR
ListenV1ConfigureobjectRequired

Updates the configuration of an open stream without reconnecting. Fields you omit keep their current values. The server answers every Configure with exactly one ConfigureSuccess or ConfigureFailure message. On failure, the stream keeps its previous configuration. Only one Configure can be pending at a time; wait for its response before sending another.

Receive

ListenV1ConfigureSuccessobjectRequired

Confirms that a Configure message was applied. Echoes the fields the Configure replaced; fields it did not change are omitted.

OR
ListenV1ConfigureFailureobjectRequired

Indicates that a Configure message was rejected in full. The stream keeps its previous configuration and stays open.

OR
ListenV1ResultsobjectRequired
Deepgram has responded with a transcription
OR
ListenV1MetadataobjectRequired

Metadata event - these are usually information describing the connection

OR
ListenV1UtteranceEndobjectRequired
An utterance has ended
OR
ListenV1SpeechStartedobjectRequired

vad_events is true and speech has been detected

OR
ListenV1ErrorobjectRequired

Receive an error message from the server. The stream stays open after a SchemaError and continues with its previous settings. Fatal failures close the socket with a close frame and send no Error message. Rejected Configure messages return ConfigureFailure instead.