Pronunciation Dictionaries

Control how an agent says specific words — brand names, places, acronyms — across every voice.

A pronunciation dictionary is a named set of substitution rules that fix how an agent speaks particular words. Bind one to an agent and, just before each line is spoken, the agent rewrites the matching text — so “Lehar” becomes “luh-har” no matter which TTS provider is running.

The model

A pronunciation dictionary is a named entity in your workspace, created and edited independently of any agent. An agent points at one through pronunciation_dictionary_id:

• One dictionary per agent. An agent applies exactly the dictionary it is bound to.
• Many agents per dictionary. Several agents can share one dictionary.
• Provider-agnostic. Rules are applied as a text substitution before the words reach text-to-speech, so they behave identically for Sarvam, Murf, ElevenLabs, Edge, and every other provider.
• Read for all, write for admins. Every workspace member can list and attach dictionaries (pronunciation_dictionary:read); only admins can create, edit, or delete them (pronunciation_dictionary:write).
• Names are unique within a workspace; creating a duplicate returns 409.

Manage dictionaries

Method	Path	Scope	Notes
GET	/pronunciation-dictionaries	pronunciation_dictionary:read	List (paginated), each with an entry_count.
POST	/pronunciation-dictionaries	pronunciation_dictionary:write	name (required), description?, entries?. Returns 201.
PATCH	/pronunciation-dictionaries/{id}	pronunciation_dictionary:write	Partial update. Sending entries replaces the whole list; description: "" clears the note.
DELETE	/pronunciation-dictionaries/{id}	pronunciation_dictionary:write	Delete. Agents referencing it are auto-unbound; the response reports agents_unbound.

curl -X POST "$LEHAR_BASE_URL/pronunciation-dictionaries" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand names",
    "entries": [
      { "grapheme": "Lehar", "replacement": "luh-har", "language": "en" },
      { "grapheme": "Bengaluru", "replacement": "beng-uh-loo-roo" }
    ]
  }'

Entry shape

Each entry is a single rule. A dictionary holds up to 500 entries.

Field	Required	Notes
grapheme	Yes	The written form to match (max 200 chars).
replacement	Yes	What the agent should say instead (max 500 chars).
kind	No	substitution (default) or ipa.
language	No	Optional language tag (max 32 chars) that scopes the rule to one language.

Two entries may not share the same grapheme + language, so a match is always unambiguous. substitution rewrites the spoken text and works with every provider; ipa is reserved for a future provider-native path (stored today, applied only where the catalog lists the provider under pronunciation_dictionary_ipa_providers).

Attach to an agent

Set pronunciation_dictionary_id on the agent — on create or while it is a draft:

curl -X PUT "$LEHAR_BASE_URL/agent/agent_sales_hi" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pronunciation_dictionary_id": "pd_01EXAMPLE" }'

The dictionary must belong to the same workspace. Deleting a dictionary that agents still reference simply unbinds them — their pronunciation_dictionary_id becomes null, and nothing else changes.

Agents

Bind a dictionary to an agent.

Providers & Models

Where voices are chosen.