TIL: Deepgram keyterm prompting for accurate transcription
TIL Tuesday: Deepgram’s keyterm parameter is a single query string addition that tells the STT model to listen harder for specific words. I spent months watching transcripts mangle company names and technical terms before I started using it. The fix was one parameter I should have added on day one.
The keyterm parameter biases the model toward the words you pass. Product names, acronyms, industry jargon, unusual surnames, anything the generic model would guess instead of transcribe correctly. No retraining, no custom vocabulary upload, just a list of terms in the query string.
curl -X POST "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=Deepgram&keyterm=Nova-3" \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: audio/wav" \
--data-binary @audio.wavHow keyterm prompting is different from legacy keywords
If you used Deepgram before Nova-3, you probably used keywords with a weight syntax like keywords=term:2. That feature still works on older models. Keyterm prompting is a different system with different rules.
Keyterm prompting does not accept weights. The old keywords=acme:5 syntax is silently accepted but the weight is ignored. The whole string gets treated as a literal keyterm, so acme:5 would try to boost the literal string “acme:5”. This caught me out the first time I migrated.
Keyterm prompting supports up to 500 tokens per request, which is roughly 100 words or phrases. Each phrase is one parameter. For multi-word phrases you join the words with %20 or + in the URL:
curl -X POST "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=customer%20service&keyterm=account%20number" \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: audio/wav" \
--data-binary @audio.wavMultiple keyterms go as repeated keyterm parameters. Do not separate them with commas or semicolons. The API accepts them without error but treats the whole string as one term, which silently does nothing.
When keyterm prompting actually matters
The difference shows in the edge cases. A generic STT model hears “I work at DPG” when the speaker said “I work at Deepgram.” It hears “let me check the TOS” when they said “let me check the TTS.” These are not model failures. They are the model optimising for the most probable word given the acoustic signal, and the most probable word is not always the right one.
I saw this constantly in Deepgram’s Discord. A developer integrating a voice agent for a pharmacy would get “CVS” transcribed correctly but “Walgreens” would come back as “wall greens” or “wall greens.” Not because the model had a problem with the audio. Because “Walgreens” is a proper noun the model had heard fewer times in training than the phonetic alternatives.
Keyterm prompting solves that without retraining. You pass keyterm=Walgreens in the query string and the model adjusts its decoder bias toward that sequence of phonemes. The same audio that produced “wall greens” now produces “Walgreens.”
Using keyterm prompting with the Deepgram SDK
The same parameter is available through the SDKs. In Python:
from deepgram import DeepgramClient
client = DeepgramClient(api_key="YOUR_API_KEY")
with client.listen.v1.connect(
model="nova-3",
keyterm=["Deepgram", "Nova-3", "keyterm prompting"]
) as connection:
connection.on(EventType.MESSAGE, lambda msg: print(msg))
connection.start_listening()The SDK accepts keyterms as a list of strings. The parameter name is keyterm (singular), not keyterms. I made that mistake and spent ten minutes wondering why nothing changed.
The limits and gotchas
Keyterm prompting works with Nova-3 and Flux models. It does not work with Nova-2 or older models. If you are on an older model and try it, the API returns a “Bad Request” error: “The selected model does not support keyterm prompting.”
The 500-token limit covers all keyterms combined, not per term. If you need more than that, you need a different strategy. For most use cases 500 tokens is plenty. A pharmacy voice agent might need 30 or 40 drug names. A legal transcription service might need 60 or 70 case names and legal terms. Both fit easily.
Dynamic keyterm updates are a Flux-only feature. With Flux you can send a Configure message mid-stream to swap keyterms as the conversation context changes. With Nova-3 the keyterm list is fixed at connection time.
FAQ
What is Deepgram keyterm prompting?
Keyterm prompting is a query parameter on Deepgram’s STT API that biases the model toward specific words and phrases. You pass a list of terms and the model prioritises them during decoding, improving accuracy for proper nouns, jargon, and domain terminology without retraining.
How do I use keyterm prompting?
Add keyterm=TERM to your API request URL. For the REST API it goes in the query string. For streaming it is a connection parameter. Multiple terms use repeated keyterm parameters. The feature is available on Nova-3 and Flux models.
How is keyterm different from the old keywords feature?
Keywords accepted weights like keywords=term:5 to control bias intensity. Keyterm prompting does not support weights. It also uses a different internal mechanism that integrates with the decoder rather than reranking hypotheses. If you pass a weight with keyterm, it is silently ignored.
Can I update keyterms mid-stream?
With Flux, yes. Send a Configure control message over the WebSocket with a new keyterm list. With Nova-3, no. The keyterm list is locked at connection time.
What is the keyterm limit?
500 tokens total across all keyterms in a single request. Roughly 100 words or phrases. If you exceed the limit the API returns an error.