# Custom vocabulary

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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`.

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

| Mode  | Scope                                  |
| ----- | -------------------------------------- |
| Fast  | Current request                        |
| Batch | Current job and all of its input files |
| Live  | Current WebSocket session              |

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

```json
{
    "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.

```shell
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`.

```json
{
    "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.

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

## Manage Vocabulary Assets

| Action | Endpoint                                                |
| ------ | ------------------------------------------------------- |
| Create | `POST /aiservices/assets/vocabularies`                  |
| List   | `GET /aiservices/assets/vocabularies`                   |
| Get    | `GET /aiservices/assets/vocabularies/{vocabularyId}`    |
| Delete | `DELETE /aiservices/assets/vocabularies/{vocabularyId}` |

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`.