The Deepgram Speech-to-Text API provides accurate, fast transcription of audio content using advanced AI models. It supports both pre-recorded audio files and real-time streaming audio, delivering transcripts in under 300 milliseconds. The API includes features such as punctuation, diarization, language detection, smart formatting, and support for multiple languages and audio formats.
openapi: 3.1.0
info:
title: Deepgram Speech-to-Text API
description: >-
The Deepgram Speech-to-Text API provides accurate, fast transcription of
audio content using advanced AI models. It supports pre-recorded audio
files, delivering transcripts with features such as punctuation,
diarization, language detection, smart formatting, summarization,
sentiment analysis, topic detection, and intent recognition. Deepgram's
Nova model family powers the transcription engine, offering high accuracy
for conversational and professional audio across multiple languages and
audio formats.
version: '1.0'
contact:
name: Deepgram Support
url: https://developers.deepgram.com
termsOfService: https://deepgram.com/tos
externalDocs:
description: Deepgram Speech-to-Text Documentation
url: https://developers.deepgram.com/docs/stt/getting-started
servers:
- url: https://api.deepgram.com
description: Deepgram Production Server
- url: https://api.eu.deepgram.com
description: Deepgram EU Server
tags:
- name: Pre-Recorded
description: >-
Transcribe pre-recorded audio files or audio from URLs.
- name: Text Intelligence
description: >-
Analyze text content for summarization, sentiment, topics, and intents.
security:
- bearerAuth: []
paths:
/v1/listen:
post:
operationId: transcribePreRecordedAudio
summary: Deepgram Transcribe pre-recorded audio
description: >-
Transcribes and optionally analyzes pre-recorded audio. Accepts audio
as a URL reference in the request body or as raw binary audio data.
Supports a wide range of audio formats and provides options for
punctuation, diarization, smart formatting, language detection,
summarization, sentiment analysis, topic detection, and intent
recognition through query parameters.
tags:
- Pre-Recorded
parameters:
- $ref: '#/components/parameters/model'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/punctuate'
- $ref: '#/components/parameters/diarize'
- $ref: '#/components/parameters/diarize_version'
- $ref: '#/components/parameters/smart_format'
- $ref: '#/components/parameters/utterances'
- $ref: '#/components/parameters/utt_split'
- $ref: '#/components/parameters/keywords'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/replace'
- $ref: '#/components/parameters/redact'
- $ref: '#/components/parameters/paragraphs'
- $ref: '#/components/parameters/detect_language'
- $ref: '#/components/parameters/filler_words'
- $ref: '#/components/parameters/multichannel'
- $ref: '#/components/parameters/alternatives'
- $ref: '#/components/parameters/numerals'
- $ref: '#/components/parameters/tag'
- $ref: '#/components/parameters/callback'
- $ref: '#/components/parameters/callback_method'
- $ref: '#/components/parameters/sentiment'
- $ref: '#/components/parameters/summarize'
- $ref: '#/components/parameters/topics'
- $ref: '#/components/parameters/intents'
- $ref: '#/components/parameters/extra'
requestBody:
description: >-
Audio content to transcribe. Can be a JSON object with a URL
reference or raw binary audio data with the appropriate
Content-Type header.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AudioUrlRequest'
audio/*:
schema:
type: string
format: binary
description: >-
Raw binary audio data in any supported audio format.
responses:
'200':
description: Transcription completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TranscriptionResponse'
'400':
description: Bad request due to invalid parameters or audio format
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/read:
post:
operationId: analyzeText
summary: Deepgram Analyze text content
description: >-
Analyzes text content for summarization, sentiment analysis, topic
detection, and intent recognition using Deepgram's text intelligence
models. Accepts text as a string in a JSON request body, a local
file, or a hosted URL.
tags:
- Text Intelligence
parameters:
- $ref: '#/components/parameters/sentiment'
- $ref: '#/components/parameters/summarize'
- $ref: '#/components/parameters/topics'
- $ref: '#/components/parameters/intents'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/callback'
- $ref: '#/components/parameters/callback_method'
- $ref: '#/components/parameters/custom_topic'
requestBody:
description: >-
Text content to analyze. Can be a JSON object with a text string
or a URL to a text document.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextAnalysisRequest'
responses:
'200':
description: Text analysis completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TextAnalysisResponse'
'400':
description: Bad request due to invalid parameters or input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Deepgram API key passed as a bearer token in the Authorization header.
tokenAuth:
type: apiKey
in: header
name: Authorization
description: >-
Deepgram API key passed with Token prefix, e.g. Token YOUR_API_KEY.
parameters:
model:
name: model
in: query
description: >-
AI model used to process the audio. Options include nova-3, nova-2,
nova, enhanced, and base.
schema:
type: string
default: nova-3
language:
name: language
in: query
description: >-
BCP-47 language tag for the primary spoken language in the audio.
schema:
type: string
example: en
punctuate:
name: punctuate
in: query
description: >-
Indicates whether to add punctuation and capitalization to the
transcript.
schema:
type: boolean
default: false
diarize:
name: diarize
in: query
description: >-
Indicates whether to recognize speaker changes in the transcript.
schema:
type: boolean
default: false
diarize_version:
name: diarize_version
in: query
description: >-
Version of the diarization feature to use.
schema:
type: string
smart_format:
name: smart_format
in: query
description: >-
Indicates whether to apply smart formatting which synchronizes
punctuation, diarization, and intelligent text normalization.
schema:
type: boolean
default: false
utterances:
name: utterances
in: query
description: >-
Indicates whether to segment speech into utterances.
schema:
type: boolean
default: false
utt_split:
name: utt_split
in: query
description: >-
Length of time in seconds used to split utterances.
schema:
type: number
format: float
keywords:
name: keywords
in: query
description: >-
Keywords to boost in the transcription results.
schema:
type: array
items:
type: string
search:
name: search
in: query
description: >-
Terms to search for in the submitted audio.
schema:
type: array
items:
type: string
replace:
name: replace
in: query
description: >-
Terms or phrases to search for in the submitted audio and replace.
schema:
type: array
items:
type: string
redact:
name: redact
in: query
description: >-
Indicates whether to redact sensitive information from the transcript.
Accepts boolean or specific entity types such as pci, numbers, ssn.
schema:
type: array
items:
type: string
paragraphs:
name: paragraphs
in: query
description: >-
Indicates whether to split the transcript into paragraphs.
schema:
type: boolean
default: false
detect_language:
name: detect_language
in: query
description: >-
Indicates whether to detect the language of the audio.
schema:
type: boolean
default: false
filler_words:
name: filler_words
in: query
description: >-
Indicates whether to include filler words such as um and uh in the
transcript.
schema:
type: boolean
default: false
multichannel:
name: multichannel
in: query
description: >-
Indicates whether to transcribe each audio channel independently.
schema:
type: boolean
default: false
alternatives:
name: alternatives
in: query
description: >-
Maximum number of transcript alternatives to return.
schema:
type: integer
minimum: 1
numerals:
name: numerals
in: query
description: >-
Indicates whether to convert numbers from written format to
numerical format.
schema:
type: boolean
default: false
tag:
name: tag
in: query
description: >-
Tag to associate with the request for tracking purposes.
schema:
type: array
items:
type: string
callback:
name: callback
in: query
description: >-
URL to which Deepgram will make a callback request when processing
is complete.
schema:
type: string
format: uri
callback_method:
name: callback_method
in: query
description: >-
HTTP method for the callback request.
schema:
type: string
enum:
- POST
- PUT
default: POST
sentiment:
name: sentiment
in: query
description: >-
Indicates whether to perform sentiment analysis on the content.
schema:
type: boolean
default: false
summarize:
name: summarize
in: query
description: >-
Indicates whether to generate a summary of the content. Can be a
boolean or a specific summary format.
schema:
type: string
topics:
name: topics
in: query
description: >-
Indicates whether to detect topics in the content.
schema:
type: boolean
default: false
intents:
name: intents
in: query
description: >-
Indicates whether to detect intents in the content.
schema:
type: boolean
default: false
extra:
name: extra
in: query
description: >-
Arbitrary key-value pairs to associate with the request.
schema:
type: string
custom_topic:
name: custom_topic
in: query
description: >-
Custom topics to detect within the input content. Up to 100 custom
topics are allowed.
schema:
type: array
items:
type: string
schemas:
AudioUrlRequest:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: >-
URL of the audio file to transcribe.
TextAnalysisRequest:
type: object
properties:
text:
type: string
description: >-
Text content to analyze.
url:
type: string
format: uri
description: >-
URL of a text document to analyze.
TranscriptionResponse:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
results:
$ref: '#/components/schemas/Results'
Metadata:
type: object
properties:
transaction_key:
type: string
description: >-
Unique identifier for the transaction.
request_id:
type: string
description: >-
Unique identifier for the API request.
sha256:
type: string
description: >-
SHA-256 hash of the submitted audio.
created:
type: string
format: date-time
description: >-
Timestamp when the request was created.
duration:
type: number
format: float
description: >-
Duration of the submitted audio in seconds.
channels:
type: integer
description: >-
Number of audio channels detected.
models:
type: array
items:
type: string
description: >-
Model identifiers used for transcription.
model_info:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelInfo'
description: >-
Detailed information about models used.
ModelInfo:
type: object
properties:
name:
type: string
description: >-
Name of the model.
version:
type: string
description: >-
Version of the model.
arch:
type: string
description: >-
Architecture of the model.
Results:
type: object
properties:
channels:
type: array
items:
$ref: '#/components/schemas/Channel'
description: >-
Transcription results organized by audio channel.
utterances:
type: array
items:
$ref: '#/components/schemas/Utterance'
description: >-
Transcription results organized by utterance when utterances
parameter is enabled.
summary:
$ref: '#/components/schemas/Summary'
sentiments:
$ref: '#/components/schemas/SentimentResults'
topics:
$ref: '#/components/schemas/TopicResults'
intents:
$ref: '#/components/schemas/IntentResults'
Channel:
type: object
properties:
alternatives:
type: array
items:
$ref: '#/components/schemas/Alternative'
description: >-
Alternative transcriptions for this channel, ordered by
confidence.
detected_language:
type: string
description: >-
Detected language of the audio in this channel.
language_confidence:
type: number
format: float
description: >-
Confidence score for the detected language.
Alternative:
type: object
properties:
transcript:
type: string
description: >-
Full transcript text for this alternative.
confidence:
type: number
format: float
description: >-
Confidence score for this alternative.
minimum: 0
maximum: 1
words:
type: array
items:
$ref: '#/components/schemas/Word'
description: >-
Individual words with timing and confidence information.
paragraphs:
$ref: '#/components/schemas/ParagraphGroup'
Word:
type: object
properties:
word:
type: string
description: >-
The transcribed word.
start:
type: number
format: float
description: >-
Start time of the word in seconds.
end:
type: number
format: float
description: >-
End time of the word in seconds.
confidence:
type: number
format: float
description: >-
Confidence score for this word.
minimum: 0
maximum: 1
speaker:
type: integer
description: >-
Speaker identifier when diarization is enabled.
punctuated_word:
type: string
description: >-
The word with punctuation applied when punctuate is enabled.
sentiment:
type: string
enum:
- positive
- negative
- neutral
description: >-
Sentiment of the word when sentiment analysis is enabled.
sentiment_score:
type: number
format: float
description: >-
Sentiment confidence score for this word.
ParagraphGroup:
type: object
properties:
transcript:
type: string
description: >-
Full transcript organized into paragraphs.
paragraphs:
type: array
items:
$ref: '#/components/schemas/Paragraph'
description: >-
Individual paragraph objects.
Paragraph:
type: object
properties:
sentences:
type: array
items:
$ref: '#/components/schemas/Sentence'
description: >-
Sentences within this paragraph.
start:
type: number
format: float
description: >-
Start time of the paragraph in seconds.
end:
type: number
format: float
description: >-
End time of the paragraph in seconds.
num_words:
type: integer
description: >-
Number of words in this paragraph.
speaker:
type: integer
description: >-
Speaker identifier for this paragraph.
Sentence:
type: object
properties:
text:
type: string
description: >-
Sentence text.
start:
type: number
format: float
description: >-
Start time of the sentence in seconds.
end:
type: number
format: float
description: >-
End time of the sentence in seconds.
Utterance:
type: object
properties:
start:
type: number
format: float
description: >-
Start time of the utterance in seconds.
end:
type: number
format: float
description: >-
End time of the utterance in seconds.
confidence:
type: number
format: float
description: >-
Confidence score for this utterance.
channel:
type: integer
description: >-
Audio channel index for this utterance.
transcript:
type: string
description: >-
Transcript text for this utterance.
words:
type: array
items:
$ref: '#/components/schemas/Word'
description: >-
Individual words within this utterance.
speaker:
type: integer
description: >-
Speaker identifier for this utterance.
id:
type: string
description: >-
Unique identifier for this utterance.
Summary:
type: object
properties:
short:
type: string
description: >-
Short summary of the content.
SentimentResults:
type: object
properties:
segments:
type: array
items:
$ref: '#/components/schemas/SentimentSegment'
description: >-
Sentiment analysis results for content segments.
average:
$ref: '#/components/schemas/SentimentAverage'
SentimentSegment:
type: object
properties:
text:
type: string
description: >-
Text of the segment.
start_word:
type: integer
description: >-
Index of the first word in this segment.
end_word:
type: integer
description: >-
Index of the last word in this segment.
sentiment:
type: string
enum:
- positive
- negative
- neutral
description: >-
Overall sentiment of the segment.
sentiment_score:
type: number
format: float
description: >-
Confidence score for the sentiment classification.
SentimentAverage:
type: object
properties:
sentiment:
type: string
enum:
- positive
- negative
- neutral
description: >-
Overall average sentiment.
sentiment_score:
type: number
format: float
description: >-
Average sentiment score.
TopicResults:
type: object
properties:
segments:
type: array
items:
$ref: '#/components/schemas/TopicSegment'
description: >-
Topic detection results for content segments.
TopicSegment:
type: object
properties:
text:
type: string
description: >-
Text of the segment.
start_word:
type: integer
description: >-
Index of the first word in this segment.
end_word:
type: integer
description: >-
Index of the last word in this segment.
topics:
type: array
items:
$ref: '#/components/schemas/Topic'
description: >-
Topics detected in this segment.
Topic:
type: object
properties:
topic:
type: string
description: >-
Detected topic label.
confidence_score:
type: number
format: float
description: >-
Confidence score for the topic detection.
IntentResults:
type: object
properties:
segments:
type: array
items:
$ref: '#/components/schemas/IntentSegment'
description: >-
Intent recognition results for content segments.
IntentSegment:
type: object
properties:
text:
type: string
description: >-
Text of the segment.
start_word:
type: integer
description: >-
Index of the first word in this segment.
end_word:
type: integer
description: >-
Index of the last word in this segment.
intents:
type: array
items:
$ref: '#/components/schemas/Intent'
description: >-
Intents detected in this segment.
Intent:
type: object
properties:
intent:
type: string
description: >-
Detected intent label.
confidence_score:
type: number
format: float
description: >-
Confidence score for the intent recognition.
TextAnalysisResponse:
type: object
properties:
metadata:
type: object
properties:
request_id:
type: string
description: >-
Unique identifier for the API request.
created:
type: string
format: date-time
description: >-
Timestamp when the request was created.
results:
type: object
properties:
summary:
$ref: '#/components/schemas/Summary'
sentiments:
$ref: '#/components/schemas/SentimentResults'
topics:
$ref: '#/components/schemas/TopicResults'
intents:
$ref: '#/components/schemas/IntentResults'
Error:
type: object
properties:
err_code:
type: string
description: >-
Error code identifying the type of error.
err_msg:
type: string
description: >-
Human-readable error message.
request_id:
type: string
description: >-
Unique identifier for the request that produced the error.