v3

latestOpenAPI 3.1.02026-08-0150254154.0 KB
listen > v1 > media

Transcribe and analyze pre-recorded audio and video

Transcribe audio and video using Deepgram's speech-to-text REST API

post/v1/listen

Query parameters

callbackstring

URL to which we'll make the callback request

callback_method'POST' | 'PUT'

HTTP method by which the callback request will be made

string
OR
string[]

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

sentimentboolean

Recognizes the sentiment throughout a transcript or text

'v2'
OR
boolean

Summarize content. For Listen API, supports string version option. For Read API, accepts boolean only.

string
OR
string[]

Label your requests for the purpose of identification during usage reporting

topicsboolean

Detect topics throughout a transcript or text

string
OR
string[]

Custom topics you want the model to detect within your input audio or text if present Submit up to 100.

custom_topic_mode'extended' | 'strict'

Sets how the model will interpret strings submitted to the custom_topic param. When strict, the model will only return topics submitted using the custom_topic param. When extended, the model will return its own detected topics in addition to those submitted using the custom_topic param

intentsboolean

Recognizes speaker intent throughout a transcript or text

string
OR
string[]

Custom intents you want the model to detect within your input audio if present

custom_intent_mode'extended' | 'strict'

Sets how the model will interpret intents submitted to the custom_intent param. When strict, the model will only return intents submitted using the custom_intent param. When extended, the model will return its own detected intents in the custom_intent param.

detect_entitiesboolean

Identifies and extracts key entities from content in submitted audio

boolean
OR
string[]

Identifies the dominant language spoken in submitted audio

diarizeboolean

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

diarize_model'latest' | 'v1' | 'v2'

Select and enable a specific diarization model version. Specifying this parameter enables diarization and selects the model — you do not need to also set the deprecated diarize=true parameter. For batch, supported values are latest (currently v2), v1, and v2. For streaming, supported values are latest (currently v1) and v1; v2 returns a validation error on streaming requests.

dictationboolean

Dictation mode for controlling formatting with dictated speech

encoding'linear16' | 'flac' | 'mulaw' | 'amr-nb' | 'amr-wb' | 'opus' | 'speex' | 'g729'

Specify the expected encoding of your submitted audio

filler_wordsboolean

Filler Words can help transcribe interruptions in your audio, like "uh" and "um"

keytermstring[]

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.

string
OR
string[]

Keywords can boost or suppress specialized terminology and brands

languagestring

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

measurementsboolean

Spoken measurements will be converted to their corresponding abbreviations

'nova-3' | 'nova-3-general' | 'nova-3-medical' | 'nova-2' | 'nova-2-general' | 'nova-2-meeting' | 'nova-2-finance' | 'nova-2-conversationalai' | 'nova-2-voicemail' | 'nova-2-video' | 'nova-2-medical' | 'nova-2-drivethru' | 'nova-2-automotive' | 'nova' | 'nova-general' | 'nova-phonecall' | 'nova-medical' | 'enhanced' | 'enhanced-general' | 'enhanced-meeting' | 'enhanced-phonecall' | 'enhanced-finance' | 'base' | 'meeting' | 'phonecall' | 'finance' | 'conversationalai' | 'voicemail' | 'video'

Our public models available to all accounts

OR
string

AI model used to process submitted audio

multichannelboolean

Transcribe each audio channel independently

numeralsboolean

Numerals converts numbers from written format to numerical format

paragraphsboolean

Splits audio into paragraphs to improve transcript readability

profanity_filterboolean

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

punctuateboolean

Add punctuation and capitalization to the transcript

string
OR
V1ListenPostParametersRedactSchemaOneOf1Items[]

Redaction removes sensitive information from your transcripts

string
OR
string[]

Search for terms or phrases in submitted audio and replaces them

string
OR
string[]

Search for terms or phrases in submitted audio

smart_formatboolean

Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability

utterancesboolean

Segments speech into meaningful semantic units

utt_splitnumber double

Seconds to wait before detecting a pause between words in submitted audio

'latest'

Use the latest version of a model

OR
string

Version of an AI model to use

mip_opt_outboolean

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

Headers

Authorizationstring required

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

Request body

urlstring uri required

Response

Returns either transcription results, or a request_id when using a callback.

OR