Skip to main content

Documentation Index

Fetch the complete documentation index at: https://voice.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.