Pronunciation Dictionaries - Voice AI Developer Docs

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

Dictionary content is versioned. When you pass dictionary_id without dictionary_version, Voice.ai uses the latest version.

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 endpoint for the full request and response schema.

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
      }
    ]
  }'

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);

Upload a PLS File

If you already have a pronunciation lexicon, upload it directly: See the Create pronunciation dictionary from PLS file endpoint for details.

cURL

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 "[email protected]"

Update Rules

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

Replace pronunciation dictionary rules Replaces the entire rule set with POST /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/set-rules.
Add pronunciation dictionary rules Adds new rules with POST /api/v1/tts/pronunciation-dictionaries/{dictionary_id}/add-rules.
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 GET /api/v1/tts/pronunciation-dictionaries
Get pronunciation dictionary GET /api/v1/tts/pronunciation-dictionaries/{dictionary_id}

Rename without creating a new version:

Rename pronunciation dictionary PATCH /api/v1/tts/pronunciation-dictionaries/{dictionary_id}

Delete a dictionary permanently:

Delete pronunciation dictionary DELETE /api/v1/tts/pronunciation-dictionaries/{dictionary_id}

Download any saved version as PLS:

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.

cURL

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:

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

​Rule Format

​Create From Rules

​Upload a PLS File

​Update Rules

​Use With Direct TTS Requests

​Use With Voice Agents

​Related Guides

Rule Format

Create From Rules

Upload a PLS File

Update Rules

Use With Direct TTS Requests

Use With Voice Agents

Related Guides