Skip to main content
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

LimitValue
Dictionaries per organization50
Items per dictionary100
Text field (match)200 characters
Alias / phoneme value500 characters
File upload1 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