> ## Documentation Index
> Fetch the complete documentation index at: https://voice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation Dictionaries

> Create managed pronunciation dictionaries, version them, and apply them to direct TTS requests or voice agents.

Use pronunciation dictionaries to control how specific words or phrases are spoken.

Voice.ai supports managed pronunciation dictionaries with explicit versions. You can:

* create a dictionary from rules
* upload a `.pls` file
* update rules over time
* download any version as PLS
* apply a dictionary to direct TTS requests
* assign a dictionary to an agent through `tts_params`

<Info>
  Dictionary content is versioned. When you pass `dictionary_id` without `dictionary_version`, Voice.ai uses the latest version.
</Info>

## Rule Format

Rules use a compact TTS-oriented shape:

| Field            | Type    | Required | Description                                             |
| ---------------- | ------- | -------- | ------------------------------------------------------- |
| `word`           | string  | Yes      | Word or phrase to match.                                |
| `replacement`    | string  | Yes      | Replacement pronunciation text.                         |
| `ipa`            | string  | No       | Optional phonetic pronunciation string.                 |
| `case_sensitive` | boolean | No       | Whether matching is case sensitive. Defaults to `true`. |

If `ipa` is omitted, the rule is treated as a text replacement rule.

## Create From Rules

Create a managed dictionary by posting an initial rule set:

See the [Create pronunciation dictionary from rules](/docs/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary-from-rules) endpoint for the full request and response schema.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://dev.voice.ai/api/v1/tts/pronunciation-dictionaries/add-from-rules" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Cars",
      "language": "en",
      "rules": [
        {
          "word": "RAV4",
          "replacement": "rav four",
          "case_sensitive": true
        },
        {
          "word": "routeur",
          "replacement": "roo-tuhr",
          "ipa": "ʁutœʁ",
          "case_sensitive": false
        }
      ]
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://dev.voice.ai/api/v1/tts/pronunciation-dictionaries/add-from-rules', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Cars',
      language: 'en',
      rules: [
        { word: 'RAV4', replacement: 'rav four', case_sensitive: true },
        { word: 'routeur', replacement: 'roo-tuhr', ipa: 'ʁutœʁ', case_sensitive: false }
      ]
    })
  });

  const dictionary = await response.json();
  console.log(dictionary.id, dictionary.current_version);
  ```
</CodeGroup>

## Upload a PLS File

If you already have a pronunciation lexicon, upload it directly:

See the [Create pronunciation dictionary from PLS file](/docs/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary-from-pls-file) endpoint for details.

```bash cURL theme={null}
curl -X POST "https://dev.voice.ai/api/v1/tts/pronunciation-dictionaries/add-from-file" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Support Terms" \
  -F "language=en" \
  -F "file=@support-terms.pls"
```

## Update Rules

Managed dictionaries are versioned. These endpoints create a new version:

* [Replace pronunciation dictionary rules](/docs/api-reference/pronunciation-dictionaries/replace-pronunciation-dictionary-rules)
  Replaces the entire rule set with `POST /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/set-rules`.
* [Add pronunciation dictionary rules](/docs/api-reference/pronunciation-dictionaries/add-pronunciation-dictionary-rules)
  Adds new rules with `POST /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/add-rules`.
* [Remove pronunciation dictionary rules](/docs/api-reference/pronunciation-dictionaries/remove-pronunciation-dictionary-rules)
  Removes rules by stable `rule_ids` with `POST /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/remove-rules`.

You can inspect the current rules and version history with:

* [List pronunciation dictionaries](/docs/api-reference/pronunciation-dictionaries/list-pronunciation-dictionaries)
  `GET /api/v1/tts/pronunciation-dictionaries`
* [Get pronunciation dictionary](/docs/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary)
  `GET /api/v1/tts/pronunciation-dictionaries/{dictionary_id}`

Rename without creating a new version:

* [Rename pronunciation dictionary](/docs/api-reference/pronunciation-dictionaries/rename-pronunciation-dictionary)
  `PATCH /api/v1/tts/pronunciation-dictionaries/{dictionary_id}`

Delete a dictionary permanently:

* [Delete pronunciation dictionary](/docs/api-reference/pronunciation-dictionaries/delete-pronunciation-dictionary)
  `DELETE /api/v1/tts/pronunciation-dictionaries/{dictionary_id}`

Download any saved version as PLS:

* [Download pronunciation dictionary version as PLS](/docs/api-reference/pronunciation-dictionaries/download-pronunciation-dictionary-version-as-pls)
  `GET /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/{version}/download`

## Use With Direct TTS Requests

Pass `dictionary_id` and, optionally, `dictionary_version` in your TTS request.

```bash cURL theme={null}
curl -X POST "https://dev.voice.ai/api/v1/tts/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --output output.mp3 \
  -d '{
    "text": "The RAV4 coupe is ready for pickup.",
    "dictionary_id": "YOUR_DICTIONARY_ID",
    "dictionary_version": 3
  }'
```

If you omit `dictionary_version`, Voice.ai uses the latest version.

## Use With Voice Agents

Pronunciation dictionaries can also be attached to a saved agent through `config.tts_params`:

```json theme={null}
{
  "config": {
    "tts_params": {
      "voice_id": "YOUR_VOICE_ID",
      "dictionary_id": "YOUR_DICTIONARY_ID",
      "dictionary_version": 3
    }
  }
}
```

Use `dictionary_version` only when you want to pin the agent to a specific saved version. Otherwise, omit it and the agent will use the latest version.

## Related Guides

* [Text-to-Speech Quickstart](/docs/guides/text-to-speech/quickstart)
* [Voice Agent Configuration](/docs/guides/voice-agents/configuration)
* [API Reference](/docs/api-reference)