Speech Recognition API (1.0.0)

Deepgram's Speech Recognition API gives you streamlined access to automatic transcription from Deepgram's off-the-shelf and trained speech recognition models. This feature is very fast, can understand nearly every audio format available, and is customizable. You can customize your transcript using various query parameters and apply general purpose and custom-trained AI models.

Server

URL
https://brain.deepgram.com/v2

Authentication

Basic

All requests to the API should include a basic Authorization header that references a Base64-encoded username and password.

For example, for user gandalf with password mellon, the base64-encoded value of gandalf:mellon is Z2FuZGFsZjptZWxsb24=. So Gandalf's requests to the Deepgram API should all include the following header: Authorization: Basic Z2FuZGFsZjptZWxsb24=.

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

Transcription

High-speed transcription of audio.

Transcribe pre-recorded audio

post/listen

Transcribes the specified audio file.

Query Parameters

Name Description

model

string

AI model used to process submitted audio.

Off-the-shelf Deepgram models include:

general: Optimized for everyday audio processing; if you aren't sure which model to select, start here.
meeting: Optimized for conference room settings, which include multiple speakers with a single microphone.
phonecall: Optimized for low-bandwidth audio phone calls.

You may also use a custom model associated with your account by including its custom_id.

Default: general

Possible Values: general, phonecall, meeting OR <custom-id>

Examples:

Select Example

language

string

BCP-47 language tag that hints at the primary spoken language. Language support is optimized for the following language/model combinations:

Language	Variant	Model(s)
English	en-GB	general phonecall
	en-IN	general phonecall
	en-NZ	general
	en-US	general meeting phonecall
French alpha	fr	general
Korean beta	ko	general
Portuguese alpha	pt	general
Portuguese alpha	pt-BR	general
Russian alpha	ru
Spanish beta	es	general
Turkish beta	tr	general

Default: en-US

Possible Values: en-GB, en-IN, en-NZ, en-US, es, fr, ko, pt, pt-BR, ru, tr OR null

Examples:

Select Example

punctuate

boolean

Indicates whether to add punctuation and capitalization to the transcript.

Examples:

Select Example

profanity_filter

boolean

Indicates whether to remove profanity from the transcript.

Examples:

Select Example

redact

any

Indicates whether to redact sensitive information, replacing redacted content with asterisks (*). Options include:

pci: Redacts sensitive credit card information, including credit card number, expiration date, and CVV
numbers (or true): Aggressively redacts strings of numerals

Can send multiple instances in query string (for example, redact=pci&redact=numbers).

Possible Values: pci, numbers, true OR null

Examples:

Select Example

diarize

boolean

Indicates whether to recognize speaker changes. When set to true, each word in the transcript will be assigned a speaker number starting at 0.

Examples:

Select Example

multichannel

boolean

Indicates whether to transcribe each audio channel independently. When set to true, you will receive one transcript for each channel, which means you can apply a different model to each channel using the model parameter (e.g., set model to general:phonecall, which applies the general model to channel 0 and the phonecall model to channel 1).

Examples:

Select Example

alternatives

integer

Maximum number of transcript alternatives to return. Just like a human listener, Deepgram can provide multiple possible interpretations of what it hears.

Default: 1

Example:

alternatives=1

numerals

boolean

Indicates whether to convert numbers from written format (e.g., one) to numerical format (e.g., 1). Deepgram can format numbers up to 999,999.

Converted numbers do not include punctuation. For example, 999,999 would be transcribed as 999999.

Examples:

Select Example

any

Terms or phrases to search for in the submitted audio. Deepgram searches for acoustic patterns in audio rather than text patterns in transcripts because we have noticed that acoustic pattern matching is more performant.

Can send multiple instances in query string (for example, search=speech&search=Friday).

Examples:

Select Example

callback

string

Callback URL to provide if you would like your submitted audio to be processed asynchronously. When passed, Deepgram will immediately respond with a request_id. When it has finished analyzing the audio, it will send a POST request to the provided URL with an appropriate HTTP status code.

Notes:

You may embed basic authentication credentials in the callback URL.
Only ports 80, 443, 8080, and 8443 can be used for callbacks

For streaming audio, callback can be used to redirect streaming responses to a different server:

If the callback URL begins with http:// or https://, then POST requests are sent to the callback server for each streaming response.
If the callback URL begins with ws:// or wss://, then a WebSocket connection is established with the callback server and WebSocket text messages are sent containing the streaming responses.
If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.

Example:

callback=https://example.com/callback

keywords

any

beta Keywords to which the model should pay particular attention to boosting or suppressing to help it understand context. Just like a human listener, Deepgram can better understand mumbled, distorted, or otherwise hard-to-decipher speech when it knows the context of the conversation.

To learn more about the most effective way to use keywords and recognize context in your transcript, see our Keyword Boosting guide.

Notes:

Can send multiple instances in query string (for example, `keywords=medicine&keywords=prescription`).
Can request multi-word keywords in a percent-encoded query string (for example, `keywords=miracle%20medicine`). When Deepgram listens for your supplied keywords, it separates them into individual words, then boosts or suppresses them individually.
Can append a positive or negative intensifier to either boost or suppress the recognition of particular words. Positive and negative values can be decimals.
Follow best practices for keyword boosting

Examples:

Select Example

Request body schema

Request body when submitting pre-recorded audio. Accepts either:

raw binary audio data. In this case, include a Content-Type header set to the audio MIME type.
JSON object with a single field from which the audio can be retrieved. In this case, include a Content-Type header set to application/json.

Name	Description
url string*	url Location of audio file to transcribe.

Responses

Status	Description
200 success	200Audio submitted for transcription.

Response Schema

Name	Description
metadata object	metadata JSON-formatted ListenMetadata object.
results object	results JSON-formatted ListenResults object.

Send

curl --request POST \
  --url https://brain.deepgram.com/v2/listen \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"url":"string"}'

Response

{"metadata": {"request_id": "string",
"transaction_key": "string",
"sha256": "string",
"created": "string",
"duration": 0,
"channels": 0
},
"results": {"channels": [{"search": [{"query": "string",
"hits": [{"confidence": 0,
"start": 0,
"end": 0,
"snippet": "string"
}
]
}
],
"alternatives": [{"transcript": "string",
"confidence": 0,
"words": [{"word": "string",
"start": 0,
"end": 0,
"confidence": 0
}
]
}
]
}
]
}
}

Was this section helpful?

Yes No

Transcribe streaming audio

post/listen/stream

Deepgram provides its customers with real-time, streaming transcription via its streaming endpoints. These endpoints are high-performance, full-duplex services running over the tried-and-true WebSocket protocol, which makes integration with customer pipelines simple due to the wide array of client libraries available.

To use this endpoint, connect to wss://brain.deepgram.com/v2. TLS encryption will protect your connection and data.

All data is sent to the streaming endpoint as binary-type WebSocket messages containing payloads that are the raw audio data. Because the protocol is full-duplex, you can stream in real-time and still receive transcription responses while uploading data.

When you are finished, send an empty (length zero) binary message to the server. The server will interpret it as a shutdown command, which means it wil finish processing whatever data is still has cached, send the response to the client, send a summary metadata object, and then terminate the WebSocket connection.

To learn more about working with real-time streaming data and results, see Streaming Audio in Real-Time.

Query Parameters

Name Description

model

string

AI model used to process submitted audio.

Off-the-shelf Deepgram models include:

general: Optimized for everyday audio processing; if you aren't sure which model to select, start here.
meeting: Optimized for conference room settings, which include multiple speakers with a single microphone.
phonecall: Optimized for low-bandwidth audio phone calls.

You may also use a custom model associated with your account by including its custom_id.

Default: general

Possible Values: general, phonecall, meeting OR <custom-id>

Examples:

Select Example

language

string

BCP-47 language tag that hints at the primary spoken language. Language support is optimized for the following language/model combinations:

Language	Variant	Model(s)
English	en-GB	general phonecall
	en-IN	general phonecall
	en-NZ	general
	en-US	general meeting phonecall
French alpha	fr	general
Korean beta	ko	general
Portuguese alpha	pt	general
Portuguese alpha	pt-BR	general
Russian alpha	ru
Spanish beta	es	general
Turkish beta	tr	general

Default: en-US

Possible Values: en-GB, en-IN, en-NZ, en-US, es, fr, ko, pt, pt-BR, ru, tr OR null

Examples:

Select Example

punctuate

boolean

Indicates whether to add punctuation and capitalization to the transcript.

Examples:

Select Example

profanity_filter

boolean

Indicates whether to remove profanity from the transcript.

Examples:

Select Example

redact

any

Indicates whether to redact sensitive information, replacing redacted content with asterisks (*). Options include:

pci: Redacts sensitive credit card information, including credit card number, expiration date, and CVV
numbers (or true): Aggressively redacts strings of numerals

Can send multiple instances in query string (for example, redact=pci&redact=numbers).

Possible Values: pci, numbers, true OR null

Examples:

Select Example

diarize

boolean

Indicates whether to recognize speaker changes. When set to true, each word in the transcript will be assigned a speaker number starting at 0.

Examples:

Select Example

multichannel

boolean

Examples:

Select Example

alternatives

integer

Maximum number of transcript alternatives to return. Just like a human listener, Deepgram can provide multiple possible interpretations of what it hears.

Default: 1

Example:

alternatives=1

numerals

boolean

Indicates whether to convert numbers from written format (e.g., one) to numerical format (e.g., 1). Deepgram can format numbers up to 999,999.

Converted numbers do not include punctuation. For example, 999,999 would be transcribed as 999999.

Examples:

Select Example

any

Can send multiple instances in query string (for example, search=speech&search=Friday).

Examples:

Select Example

callback

string

Notes:

You may embed basic authentication credentials in the callback URL.
Only ports 80, 443, 8080, and 8443 can be used for callbacks

For streaming audio, callback can be used to redirect streaming responses to a different server:

If the callback URL begins with http:// or https://, then POST requests are sent to the callback server for each streaming response.
If the callback URL begins with ws:// or wss://, then a WebSocket connection is established with the callback server and WebSocket text messages are sent containing the streaming responses.
If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.

Example:

callback=https://example.com/callback

keywords

any

To learn more about the most effective way to use keywords and recognize context in your transcript, see our Keyword Boosting guide.

Notes:

Can send multiple instances in query string (for example, `keywords=medicine&keywords=prescription`).
Can request multi-word keywords in a percent-encoded query string (for example, `keywords=miracle%20medicine`). When Deepgram listens for your supplied keywords, it separates them into individual words, then boosts or suppresses them individually.
Can append a positive or negative intensifier to either boost or suppress the recognition of particular words. Positive and negative values can be decimals.
Follow best practices for keyword boosting

Examples:

Select Example

interim_results

boolean

Indicates whether the streaming endpoint should send you updates to its transcription as more audio becomes available. By default, the streaming endpoint returns regular updates, which means transcription results will likely change for a period of time. You can avoid receiving these updates by setting this flag to false.

Setting the flag to `false` increases latency (usually by several seconds) because the server will need to stabilize the transcription before returning the final results for each piece of incoming audio. If you want the lowest-latency streaming available, then set `interim_results` to `true` and handle the corrected transcripts as they are returned.

Examples:

Select Example

encoding

string

Expected encoding of the submitted streaming audio.

Options include:

linear16: 16-bit, little endian, signed PCM WAV data
flac: FLAC-encoded data
mulaw: mu-law encoded WAV data
amr-nb: adaptive multi-rate narrowband codec (sample rate must be 8000)
amr-wb: adaptive multi-rate wideband codec (sample rate must be 16000)
opus: Ogg Opus
speex: Ogg Speex

Only required when raw, headerless audio packets are sent to the streaming service. For pre-recorded audio or audio submitted to the standard `/listen` endpoint, we support over 40 popular codecs and do not require this parameter.

Possible Values: amr-nb, amr-wb, flac, linear16, mulaw, opus OR speex

Example:

encoding=flac

channels

integer

Number of independent audio channels contained in submitted streaming audio. Only read when a value is provided for encoding.

Default: 1

Example:

channels=2

sample_rate

integer

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

Example:

sample_rate=16000

Responses

Status	Description
201 success	201Audio submitted for transcription.

Response Schema

Name	Description
channel_index array	channel_index
duration number	duration Duration in seconds.
start string	start Offset in seconds.
is_final boolean	is_final Indicates final
channel object	channel

Send

// Connect to the streaming endpoint.
var establishConnection = function() {
    console.log("Establishing connection.");

    // Configure the websocket connection.
    // This requires ws installed using 'npm i ws'.
    const WebSocket = require('ws');
    socket = new WebSocket(
        'wss://brain.deepgram.com/v2/listen/stream',
        // if your base64 encoded username:password has padding ('=' signs at the end), you must strip them
        ['Basic', 'MY_BASE64_ENCODED_USERNAME:PASSWORD']
    );
    socket.onopen = (m) => {
        console.log("Socket opened!");

        // Grab an audio file.
        var fs = require('fs');
        var contents = fs.readFileSync('/path/to/audio/file.wav');

        // Send the audio to the brain api all at once (works if audio is relatively short).
        // socket.send(contents);

        // Send the audio to the brain api in chunks of 1000 bytes.
        chunk_size = 1000;
        for (i = 0; i < contents.length; i += chunk_size) {
            slice = contents.slice(i, i + chunk_size);
            socket.send(slice);
        }

        // Send the message to close the connection.
        socket.send(new Uint8Array(0));
    };
    socket.onclose = (m) => {
        console.log("Socket closed.");
    };

    socket.onmessage = (m) => {
        m = JSON.parse(m.data);
        // Log the received message.
        console.log(m);

        // Log just the words from the received message.
        if (m.hasOwnProperty('channel')) {
            let words = m.channel.alternatives[0].words;
            console.log(words);
        }
    };
};

var socket = null;
establishConnection();

Response

{"channel_index": [{"channel": "string",
"num_channels": 0
}
],
"duration": 0,
"start": "string",
"is_final": true,
"channel": {"alternatives": [{"transcript": "string",
"confidence": 0,
"words": [{"word": "string",
"start": 0,
"end": 0,
"confidence": 0
}
]
}
]
}
}

Was this section helpful?

Yes No

API Keys

Generate API keys.

Create a new key

post/keys

Don't want to reuse your username and password in your requests? Don't want to share credentials within your team? Want to have separate credentials for your staging and production systems? No problem: generate all the API keys you need and use them just as you would your username and password.

This is the only opportunity to retrieve your API secret, so be sure to record it someplace safe.

Request body schema

Request body when creating an API key.

Name	Description
label string	label User-friendly name of the API Key. Example: My API Key

Responses

Status	Description
201 success	201API Key generated

Response Schema

Name	Description
key string	key Your new API key. This should replace your username in authentication requests.
secret string	secret Your new secret. This should replace your password in authentication requests.
label string	label The user-friendly name of the API key that you submitted in the body of the request.

Send

curl --request POST \
  --url https://brain.deepgram.com/v2/keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"label":"My API Key"}'

Response

{"key": "string",
"secret": "string",
"label": "string"
}

Was this section helpful?

Yes No

Get all keys

get/keys

Returns the list of keys associated with your account.

Responses

Status	Description
200 success	200API keys found
Show common responses

Response Schema

Name	Description
keys array	keys

Send

curl --request GET \
  --url https://brain.deepgram.com/v2/keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'

Response

{"keys": [{"key": "string",
"label": "string"
}
]
}

Was this section helpful?

Yes No

Delete a key

delete/keys

Deletes the specified key. Provide a key to delete in a JSON object body.

Responses

Status	Description
204 success	204The API key was deleted.
Show common responses

Send

curl --request DELETE \
  --url https://brain.deepgram.com/v2/keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'

Was this section helpful?

Yes No