Custom vocabulary

Custom vocabulary helps Scribe recognize names, acronyms, and technical terms. Use it for people, organizations, product names, and other domain-specific language.

Scribe supports two vocabulary forms:

• config.vocabulary contains an inline vocabulary for one Fast request, Batch job, or Live session.
• config.vocabulary_id references a persistent, immutable Vocabulary Asset.

Use one or the other in a request, not both.

Both inline vocabularies and Vocabulary Assets support up to 100 phrases.

Use inline vocabulary#

Include up to 100 phrases in config.vocabulary.phrases.

{
    "config": {
        "language": "en-US",
        "vocabulary": {
            "phrases": ["Jane Chen", "Project Atlas", "Zoom AI Companion"]
        }
    }
}

During a Live session, send another session.update event to replace the active inline vocabulary for subsequent recognition.

{
    "type": "session.update",
    "config": {
        "vocabulary": {
            "phrases": ["Project Apollo", "Jane Chen"]
        }
    }
}

Create a Vocabulary Asset#

Use a Vocabulary Asset when you need to reuse a phrase list across requests or sessions.

POST /aiservices/assets/vocabularies

Put phrases at the top level of the request body and include at least one phrase. This endpoint does not currently accept a nested vocabulary: { "phrases": [...] } object. The nested config.vocabulary.phrases structure applies only to inline vocabulary in transcription requests and Live sessions.

curl -X POST https://api.zoom.us/v2/aiservices/assets/vocabularies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme English Vocabulary",
    "language": "en-US",
    "phrases": [
      "Project Atlas",
      "ServiceNow",
      "Zoom AI Companion"
    ]
  }'

A successful request returns HTTP 200 with the asset, including its server-generated vocabulary_id.

{
    "vocabulary_id": "acct_vocab_abc123",
    "name": "Acme English Vocabulary",
    "language": "en-US",
    "phrases": ["Project Atlas", "ServiceNow", "Zoom AI Companion"]
}

Save this value and pass it as config.vocabulary_id when you use the asset.

Create and get responses can also include an updated_at field.

The registered language must be compatible with the recognition language of a request that uses the asset.

Apply a Vocabulary Asset#

Set config.vocabulary_id in any Scribe mode.

{
    "file": "https://example.com/audio.wav",
    "config": {
        "language": "en-US",
        "vocabulary_id": "acct_vocab_abc123"
    }
}

Manage Vocabulary Assets#

Deleting an asset returns HTTP 200 with an empty JSON object ({}). A subsequent get request for the deleted asset returns HTTP 404.

Vocabulary Assets are account-scoped and immutable. To change a saved vocabulary, create a new asset and use its new vocabulary_id.