Skip to main content
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:
FieldTypeRequiredDescription
wordstringYesWord or phrase to match.
replacementstringYesReplacement pronunciation text.
ipastringNoOptional phonetic pronunciation string.
case_sensitivebooleanNoWhether 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
      }
    ]
  }'

​
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: You can inspect the current rules and version history with: Rename without creating a new version: Delete a dictionary permanently: Download any saved version as PLS:

​
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.