Speech To Text

Deepgram Speech-to-Text

Deepgram transcribes audio with two model families on two endpoints. Pick the family first; the endpoint, the parameters, and the message shapes all follow from that choice. This skill gets a first request working and names the skill to open next. It does not repeat the full parameter reference; that lives in the api skill.

Pick the model family first

Decision rule:

• Choose Nova when you transcribe recorded files, generate captions or subtitles, need speaker labels, need summaries or sentiment, or stream audio where your own code decides when a phrase ends.
• Choose Flux STT when a person is talking to software and the software must know when they stopped: voice agents, phone assistants, IVR, agent assist. Flux has no prerecorded mode.
• Choose neither when you want Deepgram to also run the language model and speak the reply. That is the Voice Agent API, served from a separate host, agent.deepgram.com. Open the voice-agent skill.

First request: Nova on a prerecorded file

Create a key at https://console.deepgram.com (opens in a new tab) and export it as DEEPGRAM_API_KEY. The key goes in the Authorization header with the Token scheme. Always pass model; without it the API falls back to base.

curl -s -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://dpgr.am/spacewalk.wav"}'

The transcript is at results.channels[0].alternatives[0].transcript. To send a local file instead, set Content-Type to the audio type (for example audio/wav) and pass --data-binary @file.wav with no JSON body.

Nova options you will reach for, all query parameters on /v1/listen:

• smart_format=true adds punctuation, paragraphs, and number formatting. It turns on punctuate, so do not set both.
• diarize_model=latest labels speakers. It replaces the deprecated diarize=true; a request that sets both is rejected. Streaming accepts latest and v1 only.
• language=multi transcribes code-switched speech across the ten Nova-3 multilingual languages. Any single language code works too; the default is en.
• keyterm=<term> boosts names, product terms, and jargon. It is accepted on Nova-3 and Flux only; other models return 400 and point you at keywords. Repeat the parameter once per term. The limit is 500 tokens across all keyterms in a request, and exceeding it fails the request with Keyterm limit exceeded; Deepgram’s guidance is to stay well under it with the 20 to 50 terms that matter. Commas, semicolons, and term:weight are not rejected; the API treats the whole value as one literal term, so nothing you intended gets boosted.
• summarize=v2, sentiment=true, topics=true, and intents=true add audio intelligence. They run on prerecorded English audio only.
• Live streaming uses wss://api.deepgram.com/v1/listen?model=nova-3, the same Authorization header, and binary audio frames. During silence send {"type":"KeepAlive"} as a text frame every 3 to 5 seconds; the connection closes after 10 seconds without audio. Finish with {"type":"CloseStream"}.

Flux STT: conversational audio with turn detection

Connect over WebSocket. Flux has no REST path.

wss://api.deepgram.com/v2/listen?model=flux-general-en&encoding=linear16&sample_rate=16000

Send the same Authorization: Token header. Audio must be mono. For raw audio (linear16, linear32, mulaw, alaw, opus, ogg-opus) encoding and sample_rate are required; for WAV, Ogg, or WebM containers omit both. Send 80 ms chunks.

The server sends Connected, then a stream of TurnInfo messages. Each carries event, turn_index, transcript, words with timestamps, and end_of_turn_confidence. The event values:

• Update: roughly every 0.25 s of audio while a turn is in progress.
• StartOfTurn: the speaker began. Use it to interrupt your agent (barge-in).
• EndOfTurn: the speaker finished. Send the transcript to your language model. It carries trigger: model, manual, or timeout.
• EagerEndOfTurn and TurnResumed: emitted only when you set eager_eot_threshold. Start drafting a reply on the first; cancel it on the second.

Three query parameters tune turn detection, and all three can change mid-stream:

Client control messages, each a JSON text frame:

• {"type":"Configure","thresholds":{"eot_threshold":0.8},"keyterms":["Deepgram"]} changes thresholds, keyterms, or language_hints without reconnecting. Omitted fields keep their values; a keyterms array replaces the whole list. The reply is ConfigureSuccess or ConfigureFailure.
• {"type":"ForceEndTurn"} (added August 28, 2026) ends the current turn on your own signal: a push-to-talk release, a DTMF tone, a send button. Flux emits EndOfTurn with "trigger":"manual". With no active turn the message is ignored and a Warning with code FORCE_END_TURN_NO_ACTIVE_TURN comes back. Set eot_threshold=1.0 to drive every turn yourself.
• {"type":"CloseStream"} closes the stream.

For non-English or mixed-language calls use model=flux-general-multi, optionally with repeated language_hint=<code> parameters (for example language_hint=en&language_hint=es). Without hints the model detects the language itself. TurnInfo then includes languages and languages_hinted.

Common mistakes

1. Authorization: Bearer <api key> returns 401. API keys use Authorization: Token <key>. Bearer is only for the short-lived JWT that POST /v1/auth/grant issues.
2. A 403 with {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."} comes back both for a misspelled model name and for a real model the project cannot use. The body carries a request_id. Check the spelling before asking for access. GET https://api.deepgram.com/v1/models lists the public catalog; GET /v1/projects/{project_id}/models lists your project’s models. There is no model named nova-3-conversational; conversational audio is Flux, flux-general-en. The public catalog does not list the Flux model names, so the Flux docs are the source for those.
3. Flux on /v1/listen does not work, and model=flux is not a valid value. Use /v2/listen with flux-general-en or flux-general-multi.
4. language=en or language=multi on Flux is wrong. The model name selects the language. language_hint is accepted only by flux-general-multi and returns 400 on any other model.
5. Setting encoding or sample_rate for containerized audio (WAV, Ogg, WebM) causes errors or garbled output. Omit both and let the container declare the format.
6. ForceEndTurn on /v1/listen returns an error; it exists only on Flux.
7. smart_format, diarize, and the intelligence parameters are not available on /v2/listen. Speaker labels and summaries are a Nova job.
8. A KeepAlive sent as a binary frame is mishandled. Send control messages as text frames and audio as binary frames.

Pricing

Deepgram bills speech-to-text per minute of audio. Figures change, so read them at https://deepgram.com/pricing (opens in a new tab) rather than from any skill.

Use a different skill when

• You need every parameter, response schema, or message field: api skill, file references/listen.md.
• You want the documentation page for a topic: docs skill. The pages this skill leans on are listed under Sources.
• You want a runnable app with a UI: starters skill (the transcription, live-transcription, and flux features).
• You want a one-feature snippet under 50 lines: recipes skill, https://github.com/deepgram/recipes (opens in a new tab).
• You are wiring Deepgram into Twilio, LiveKit, Pipecat, LangChain, or another platform: examples skill.
• You want language-idiomatic SDK code: install deepgram-{js,python,java,go,rust,dotnet}-speech-to-text for Nova and deepgram-{lang}-conversational-stt for Flux from the matching SDK repository (npx skills add deepgram/deepgram-python-sdk, and so on).
• You want analysis and not just the transcript (summarize, sentiment, topics, intents, detect_entities on /v1/listen): audio-intelligence skill. For text you already have, /v1/read and the text-intelligence skill.
• You want text-to-speech or a full voice agent: the text-to-speech or voice-agent skill.
• You want a shell command rather than application code: cli skill.
• You want the docs queryable from your coding tool: setup-mcp skill.

Sources

• Getting started: https://developers.deepgram.com/docs/stt/getting-started (opens in a new tab)
• Nova prerecorded: https://developers.deepgram.com/docs/pre-recorded-audio (opens in a new tab)
• Nova live streaming: https://developers.deepgram.com/docs/live-streaming-audio (opens in a new tab) and https://developers.deepgram.com/docs/audio-keep-alive (opens in a new tab)
• Models and languages: https://developers.deepgram.com/docs/models-languages-overview