Improving Transcription with Spoken Terms

Keep company names, acronyms, and product terminology transcribed correctly in Voice API sessions by creating and maintaining a Spoken Terms collection.

In Voice API sessions, Spoken Terms ensure that the vocabulary that matters to you, such as company names, acronyms, product names, and people’s names, is transcribed with the exact spelling you choose. You provide the words, and speech recognition uses your spelling whenever they’re spoken. Unlike glossaries, Spoken Terms are monolingual. They affect how speech is recognized, not how the recognized text is translated.

This guide shows you how to set up Spoken Terms via the API and keep them current as your vocabulary grows. You can also manage them in DeepL Home.

Spoken Terms are available on all plans that include the DeepL Voice API. The number of collections you can create depends on your plan.

Collect domain-specific terms

Review your calls for domain- and company-specific words you want transcribed with complete accuracy. Collect them in a term list: the terms, written exactly as you want them to appear in your transcripts (terms are case-sensitive). In the next step, you’ll send this list to the DeepL API.

DeepL
API
webhook

Each term list holds at most 300 characters in total (see Spoken Terms Requirements for all size and content rules), so spend the budget on the terms that matter most rather than your full vocabulary.

Create a collection

Term lists are stored in a Spoken Terms collection, which can hold one term list for each language. Create a collection with POST /v3/spoken-terms:

Example request

curl -X POST https://api.deepl.com/v3/spoken-terms \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Technical Terms",
    "term_lists": [
      {
        "lang": "en",
        "entries": "DeepL\nAPI\nwebhook"
      }
    ]
}'

Example response

{
  "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Technical Terms",
  "term_lists": [
    {
      "lang": "en",
      "entry_count": 3
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Store the spoken_terms_id; every voice session that should use these terms passes it.

Start a voice session with your terms

Include the spoken_terms_id when you create a voice session. The terms for the session’s source language are then recognized correctly in the transcription:

Example request

curl -X POST https://api.deepl.com/v3/voice/realtime \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source_media_content_type": "audio/pcm; encoding=s16le; rate=16000",
    "source_language": "en",
    "target_languages": ["de"],
    "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'

See the Real-Time Voice Quickstart for an example of the full Voice API session flow.

To also control how your terms are translated, pass a glossary_id in the same session. Spoken Terms control how speech is recognized, and glossaries control how it’s translated.

Spoken Terms are available for all DeepL Voice languages. To check a language programmatically, call GET /v3/languages?resource=voice and look for the spoken_terms feature key on the source language.

Add terms as your vocabulary grows

To add terms without resending the existing ones, PATCH the collection; entries you pass for a language are merged into its existing term list:

Example request

curl -X PATCH https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "term_lists": [
      {
        "lang": "en",
        "entries": "authentication\nendpoint"
      }
    ]
}'

Example response

{
  "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Technical Terms",
  "term_lists": [
    {
      "lang": "en",
      "entry_count": 5
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Running sessions aren’t affected; the updated terms apply to sessions started after the change.

Replace a language’s terms

To rebuild a language’s term list from scratch, for example from an updated product catalog, PUT the term list with the new entries. Unlike PATCH, which adds to the existing list, PUT replaces the list entirely (or creates it, if the language is new to the collection):

Example request

curl -X PUT https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7/term-lists \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "lang": "en",
    "entries": "DeepL\nAPI\nwebhook\nintegration"
}'

Example response

{
  "lang": "en",
  "entry_count": 4
}

See the Spoken Terms reference for full details on managing collections. Size and content rules are collected in Spoken Terms Requirements.