> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.deepgram.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server. # Keyterm Prompting `keyterm` *string* Pre-recorded Streaming:Nova Streaming:Flux Instantly increase accuracy and recognition of up to 100 important terminology, product and company names, industry jargon, phrases and more. > **Info** > > Keyterm Prompting is available for both monolingual and multilingual transcription using the [Nova-3 Models](/docs/models-languages-overview#nova-3), as well as [Flux](/docs/models-languages-overview#flux). To boost recognition of keywords using another Deepgram model (such as Nova-2), use the [Keywords](/docs/keywords) feature. > **Migrating from Keywords? The syntax is different** > > `keyterm` does **not** use the weight/intensifier syntax from the legacy [Keywords](/docs/keywords) feature. `keyterm` accepts plain terms only—it does not support weights or intensifiers. The `keywords=KEYWORD:INTENSIFIER` pattern is valid for `keywords`, not for `keyterm`. > > | | Example | > | ------------------------------------------------ | ------------------------------ | > | **Do** — repeat the parameter for separate terms | `?keyterm=term1&keyterm=term2` | > | **Do** — encode a multi-word phrase with `%20` | `?keyterm=customer%20service` | > | **Do** — encode a multi-word phrase with `+` | `?keyterm=customer+service` | > | **Don't** — add a weight or intensifier | `?keyterm=term:0.15` | > | **Don't** — separate terms with a comma | `?keyterm=term1,term2` | > | **Don't** — separate terms with a semicolon | `?keyterm=term1;term2` | > > To pass multiple separate keyterms, repeat the `keyterm` parameter. To boost one multi-word phrase, join the words with `%20` or `+`. Do not separate keyterms with commas, semicolons, or line breaks. None of the **Don't** forms return an error—the API accepts the value and treats it as a single literal keyterm, so it silently boosts nothing instead of failing. ## Enable Feature To enable Keyterm Prompting, add a `keyterm` parameter in the query string and set it to your chosen key term: `keyterm=KEYTERM` To transcribe audio from a file on your computer, run the following cURL command in a terminal or your favorite API client. **`cURL`** ```bash cURL curl \ --request POST \ --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \ --header 'Content-Type: audio/wav' \ --data-binary @youraudio.wav \ --url 'https://api.deepgram.com/v1/listen?model=nova-3&keyterm=KEYTERM' ``` > **Warning** > > Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](/docs/create-additional-api-keys). ## Keyterm Examples & Best Practices The following examples demonstrate how keyterms can significantly improve recognition accuracy and confidence scores for industry-specific terminology. These examples show typical improvements you might see across Drive-Thru, IVR, call center, and medical transcription use cases. > **Note** > > The confidence scores below are illustrative examples showing typical improvement patterns. Actual results may vary based on audio quality, accent, and context. | Source | Confidence Score before | Confidence Score after | | ------------------------------ | ----------------------------------------------------- | ---------------------------------------------------- | | nacho stack double crunch taco | `"word": "macho", "confidence": 0.88728034` | `"word": "nacho", "confidence": 0.99029267` | | bacon cheeseburger | `"word": "bake in", "confidence": 0.83456712` | `"word": "bacon", "confidence": 0.98234156` | | crispy seasoned fries | `"word": "crisp he", "confidence": 0.79812345` | `"word": "crispy", "confidence": 0.97456789` | | account number | `"word": "a count", "confidence": 0.82154321` | `"word": "account", "confidence": 0.97891234` | | representative | `"word": "represent a tip", "confidence": 0.79043218` | `"word": "representative", "confidence": 0.98654321` | | billing department | `"word": "building", "confidence": 0.81234567` | `"word": "billing", "confidence": 0.96789012` | | escalation | `"word": "escalate shin", "confidence": 0.76543210` | `"word": "escalation", "confidence": 0.98123456` | | customer service | `"word": "customer", "confidence": 0.84567890` | `"word": "customer", "confidence": 0.97234567` | | technical support | `"word": "tech nil call", "confidence": 0.83456789` | `"word": "technical", "confidence": 0.98345678` | | tretinoin | `"word": "try to win", "confidence": 0.71234567` | `"word": "tretinoin", "confidence": 0.96543210` | | prescription refill | `"word": "per scription", "confidence": 0.78901234` | `"word": "prescription", "confidence": 0.97567890` | | diagnosis | `"word": "diagnose us", "confidence": 0.80123456` | `"word": "diagnosis", "confidence": 0.98901234` | | appointment scheduling | `"word": "a point men", "confidence": 0.85678901` | `"word": "appointment", "confidence": 0.98234567` | ### Best Practices for Keyterm Selection When choosing keyterms, consider the following guidelines to maximize accuracy: **Good Keyterm Examples:** * **Industry-specific terminology**: Medical terms (`tretinoin`, `diagnosis`), technical jargon (`escalation`, `API`) * **Product and company names**: Brand names, service names, competitor names * **Multi-word phrases**: Common phrases in your domain (`account number`, `customer service`) * **Proper nouns**: Names, brands, titles with appropriate capitalization (`Deepgram`, `iPhone`, `Dr. Smith`) * **Common non-proper nouns**: Use lowercase (`algorithm`, `protocol`, `refill`) **What to Avoid:** * **Generic common words**: Very common words that are rarely misrecognized (`the`, `and`, `is`) * **Overly broad terms**: Words that appear in many contexts without specific meaning * **Excessive keyterms**: Stay well under the 500 token limit; focus on the most important 20-50 terms * **Inconsistent formatting**: Ensure capitalization matches your desired output ## Case Sensitivity and Formatting Keyterms preserve formatting (including case and punctuation) which can help control how proper nouns, product names, or company names are transcribed. The model will use both the keyterm formatting and the audio context to determine the final transcription format. Best practices for keyterm formatting: * For proper nouns (names, brands, titles): Use appropriate capitalization (`Deepgram`, `iPhone`, `Dr. Smith`) * For non-proper nouns: Use lowercase (`tretinoin`, `algorithm`, `protocol`) When smart formatting is applied to the transcript, words that start sentences may be automatically capitalized regardless of keyterm formatting. Note that while the model was trained with formatted keyterms, the final transcription may not always exactly match the keyterm's formatting. The model balances the keyterm information with the audio context when determining capitalization and punctuation in the output. ## Using Multiple Keyterms A space must be properly URL-encoded to ensure compatibility. Both `%20` and `+` are valid encodings, but their usage depends on context. In URL paths, spaces must be encoded as `%20`, while in query parameters, either `%20` or `+` can be used. You can pass in multiple keyterms in your query string in several ways. Do not separate keyterms with commas, semicolons, or line breaks, and do not append a weight or intensifier—`keyterm` does not support weights. None of these forms return an error: the API accepts the value and treats it as a single literal keyterm, so a value such as `keyterm=term:0.15` silently boosts nothing rather than failing. To boost multiple separate keyterms, repeat the `keyterm` parameter so each keyterm is processed individually. **`cURL`** ```bash cURL curl \ --request POST \ --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \ --header 'Content-Type: audio/wav' \ --data-binary @youraudio.wav \ --url "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=KEYTERM1&keyterm=KEYTERM2" ``` To boost one multi-word phrase as a single keyterm, join the words with an encoded space `%20`: **`cURL`** ```bash cURL curl \ --request POST \ --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \ --header 'Content-Type: audio/wav' \ --data-binary @youraudio.wav \ --url "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=term1%20term2" ``` In query parameters, you can also join the words of a phrase with a plus `+`: **`cURL`** ```bash cURL curl \ --request POST \ --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \ --header 'Content-Type: audio/wav' \ --data-binary @youraudio.wav \ --url "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=term1+term2" ``` ## Key Term Limits Key Terms are limited to 500 tokens per request; anything beyond that will return an error like so: **`Error`** ```text Error Keyterm limit exceeded. The maximum number of tokens across all keyterms is 500. ``` The same limit applies to each mid-stream keyterm update. When you open a stream, an over-limit `keyterm` query parameter fails the connection with this error. An over-limit update sent in a [`Configure`](/docs/configure#errors) message during a Nova-3 stream returns an `Error` message instead, and the stream continues with its previous keyterms. ## Dynamic Keyterm Updates You can replace a stream's keyterms mid-stream without reconnecting, so the keyterm list can follow the conversation. For example, load product names when the caller moves to a product inquiry, or clear keyterms when they're no longer relevant. | Model | How to update keyterms mid-stream | | ------------------------------- | ------------------------------------------------------------------------- | | Nova-3 streaming (`/v1/listen`) | Send a `keyterms` array in a [`Configure`](/docs/configure) message. | | Flux STT (`/v2/listen`) | Send a `keyterms` array in a [`Configure`](/docs/flux/configure) message. | **`JSON`** ```json JSON { "type": "Configure", "keyterms": ["Deepgram", "customer service"] } ``` On both, each `keyterms` array replaces the whole list, and an empty array `[]` clears all keyterms. The [keyterm limits](#key-term-limits) apply to each update. On Nova-3, mid-stream updates work on every streaming model, monolingual and multilingual, and behave the same as keyterms set when you open the stream. Updating keyterms mid-stream isn't available for pre-recorded audio. Updating Nova-3 `keyterms` with `Configure` on `/v1/listen` is available on the global endpoint (`api.deepgram.com`). It isn't available yet on the EU (`api.eu.deepgram.com`), Australia (`api.au.deepgram.com`), or India (`api.in.deepgram.com`) [regional endpoints](/reference/regional-endpoints).