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:

{
  "text": "ASAP",
  "type": "alias",
  "alias": "as soon as possible"
}

Phoneme (IPA notation)

Specifies exact pronunciation using the International Phonetic Alphabet:

{
  "text": "GIF",
  "type": "phoneme",
  "phoneme": "ɡɪf",
  "alphabet": "ipa"
}

Using a Dictionary

Pass the dictionary ID when synthesizing speech: REST API:

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

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

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

Get a dictionary

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

Update a dictionary

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

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 format:

<?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

WebSocket Streaming

REST API

Providers

Other

API Reference

For AI Agents

Pronunciation Dictionaries

Item Types

Alias (text replacement)

Phoneme (IPA notation)

Using a Dictionary

Managing Dictionaries

Create a dictionary

List dictionaries

Get a dictionary

Update a dictionary

Delete a dictionary

Limits

File Upload Formats

​Item Types

​Alias (text replacement)

​Phoneme (IPA notation)

​Using a Dictionary

​Managing Dictionaries

​Create a dictionary

​List dictionaries

​Get a dictionary

​Update a dictionary

​Delete a dictionary

​Limits

​File Upload Formats

Item Types

Alias (text replacement)

Phoneme (IPA notation)

Using a Dictionary

Managing Dictionaries

Create a dictionary

List dictionaries

Get a dictionary

Update a dictionary

Delete a dictionary

Limits

File Upload Formats