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

# Pronunciation Dictionaries

> Control how specific words are spoken during TTS synthesis with custom pronunciation dictionaries.

Pronunciation dictionaries let you control how specific words and phrases are spoken during text-to-speech synthesis. Dictionaries are applied automatically before speech generation — no changes to your text input required.

## Item Types

Each dictionary contains up to 100 items. Two types are supported:

### Alias (text replacement)

Replaces matched text with alternative text before synthesis:

```json theme={null}
{
  "text": "ASAP",
  "type": "alias",
  "alias": "as soon as possible"
}
```

### Phoneme (IPA notation)

Specifies exact pronunciation using the International Phonetic Alphabet:

```json theme={null}
{
  "text": "GIF",
  "type": "phoneme",
  "phoneme": "ɡɪf",
  "alphabet": "ipa"
}
```

## Using a Dictionary

Pass the dictionary ID when synthesizing speech:

**REST API:**

```bash theme={null}
curl --request POST \
  --url https://api.telnyx.com/v2/text-to-speech \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "text": "Welcome to Telnyx.",
  "voice": "Telnyx.Ultra.002622d8-19d0-4567-a16a-f99c7397c062",
  "pronunciation_dict_id": "c215a3e1-be41-4701-97e8-1d3c22f9a5b7"
}'
```

**WebSocket:** pass `pronunciation_dict_id` as a query parameter on the connection URL:

```
wss://api.telnyx.com/v2/text-to-speech/speech?voice=Telnyx.Ultra.002622d8-19d0-4567-a16a-f99c7397c062&pronunciation_dict_id=c215a3e1-be41-4701-97e8-1d3c22f9a5b7
```

## Managing Dictionaries

### Create a dictionary

```bash theme={null}
curl --request POST \
  --url https://api.telnyx.com/v2/pronunciation_dicts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My Dictionary",
  "items": [
    {
      "text": "Telnyx",
      "type": "phoneme",
      "phoneme": "ˈtɛl.nɪks",
      "alphabet": "ipa"
    },
    {
      "text": "GIF",
      "type": "phoneme",
      "phoneme": "ɡɪf",
      "alphabet": "ipa"
    },
    {
      "text": "ASAP",
      "type": "alias",
      "alias": "as soon as possible"
    },
    {
      "text": "BTW",
      "type": "alias",
      "alias": "by the way"
    },
    {
      "text": "SQL",
      "type": "alias",
      "alias": "sequel"
    },
    {
      "text": "meeting",
      "type": "alias",
      "alias": "3:00 PM"
    }
  ]
}'
```

You can also upload a PLS/XML or plain text file via `multipart/form-data` instead of providing items as JSON. Plain text format:

```
Telnyx:/ˈtɛl.nɪks/
GIF:/ɡɪf/
ASAP=as soon as possible
BTW=by the way
SQL=sequel
meeting=3:00 PM
```

### List dictionaries

```bash theme={null}
curl --url 'https://api.telnyx.com/v2/pronunciation_dicts?page[number]=1&page[size]=20' \
  --header 'Authorization: Bearer <token>'
```

### Get a dictionary

```bash theme={null}
curl --url https://api.telnyx.com/v2/pronunciation_dicts/{id} \
  --header 'Authorization: Bearer <token>'
```

### Update a dictionary

```bash theme={null}
curl --request PATCH \
  --url https://api.telnyx.com/v2/pronunciation_dicts/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Brand Names v2",
  "items": [
    {
      "text": "Telnyx",
      "type": "alias",
      "alias": "tel-nicks"
    }
  ]
}'
```

Updates use optimistic locking — if the dictionary was modified concurrently, the request returns `409 Conflict`. Re-fetch and retry.

### Delete a dictionary

```bash theme={null}
curl --request DELETE \
  --url https://api.telnyx.com/v2/pronunciation_dicts/{id} \
  --header 'Authorization: Bearer <token>'
```

## Limits

| Limit                         | Value          |
| ----------------------------- | -------------- |
| Dictionaries per organization | 50             |
| Items per dictionary          | 100            |
| Text field (match)            | 200 characters |
| Alias / phoneme value         | 500 characters |
| File upload                   | 1 MB           |

## File Upload Formats

When creating a dictionary via file upload, two formats are supported:

**PLS/XML** — standard [W3C Pronunciation Lexicon Specification](https://www.w3.org/TR/pronunciation-lexicon/) format:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0"
  xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
  alphabet="ipa"
  xml:lang="en-US">
  <!-- Alias examples (text replacement) -->
  <lexeme>
    <grapheme>Telnyx</grapheme>
    <alias>tel-nicks</alias>
  </lexeme>
  <lexeme>
    <grapheme>SQL</grapheme>
    <alias>sequel</alias>
  </lexeme>
  <lexeme>
    <grapheme>IEEE</grapheme>
    <alias>I triple E</alias>
  </lexeme>
  <!-- IPA phoneme examples -->
  <lexeme>
    <grapheme>nginx</grapheme>
    <phoneme>ɛndʒɪnɛks</phoneme>
  </lexeme>
  <lexeme>
    <grapheme>kubectl</grapheme>
    <phoneme>kuːbkʌtəl</phoneme>
  </lexeme>
  <lexeme>
    <grapheme>Kubernetes</grapheme>
    <phoneme>kuːbɚnɛtɪz</phoneme>
  </lexeme>
</lexicon>
```

**Plain text** — line-based format:

* `word=alias` for alias items
* `word:/phoneme/` for IPA phonemes