Skip to main content
A pronunciation dictionary is a workspace-scoped lexicon that maps words or phrases to either a text replacement (alias) or a phonetic string (phoneme). Attach one or more dictionaries to an agent and the runtime applies the rules at speech-synthesis time so brand names, acronyms, and technical terms come out the way you want.

​
Resource hierarchy

Agents link to dictionaries through a separate locator table, written via PUT /v1/agents/:agentId/pronunciation-dictionaries. A locator carries a versionId field: null means “follow latest” (resolved at session start), a specific pdver_… ID pins the agent to that version.

​
Lifecycle

Every mutation that produces a new version triggers a Cartesia sync. Deleting a dictionary is blocked (409 dictionary_in_use) while any agent locator references it — detach all agents first.

​
Identifiers

​
Rule types

  • Alias — replaces the grapheme with spoken text before TTS. "UN" → "United Nations". Works on every TTS provider.
  • Phoneme — replaces the grapheme with an IPA or CMU phonetic string. Effective on Cartesia (server-side, IPA only — see note below), ElevenLabs Flash v2 (inline SSML, IPA or CMU), and AWS Polly Neural (inline SSML, IPA or CMU). Other models pass the rule through silently.
The alphabet (ipa or cmu) is stored per rule, but every phoneme rule in a single version must share one alphabet. The API rejects (400) any create or edit that would put both IPA and CMU phoneme rules in the same version — PLS allows exactly one <lexicon alphabet="…"> per file, so a mixed-alphabet write would silently mislabel rules on download / re-import. Split IPA and CMU entries into separate dictionaries.
Cartesia is IPA-only at the model layer. Cartesia’s hosted Pronunciation Dictionary API speaks IPA, and the sync layer converts IPA phonemes to Cartesia’s pipe format (<<a|b|c>>) automatically. CMU phoneme rules are forwarded to Cartesia verbatim — Cartesia does not speak CMU natively, so those entries fall back to the default pronunciation. If you need a phoneme rule to fire on Cartesia, author it in IPA. CMU phonemes still apply on ElevenLabs Flash v2 and AWS Polly Neural via inline SSML.

​
Cartesia server-side sync

When a new version is created, the API fires a fire-and-forget call to Cartesia’s hosted Pronunciation Dictionary API and caches the returned pronunciation_dict_id as cartesiaDictId on the version row. Subsequent reads of the same version reuse the cached ID; Cartesia is never re-asked for it. If CARTESIA_API_KEY is unset, the service logs cartesia.uploadVersion CARTESIA_API_KEY unset, skipping and the version proceeds without an ID — phoneme rules then degrade to passthrough on Cartesia voices but alias rules continue to apply via in-runtime substitution. V1 attaches one dictionary per agent to Cartesia. If multiple locators are present, the runtime passes only the first locator’s cartesia_dict_id to the Cartesia plugin and logs cartesia.multi_dict_attach for the rest.

​
How Zeptar’s API differs from ElevenLabs’s

​
Authorization

All pronunciation dictionary endpoints require an authenticated session cookie or a workspace API key. The API enforces organization scoping: every dictionary belongs to exactly one organization, and requests are scoped to the caller’s active organization. Cross-organization access returns 404 — there is no enumeration distinction between “wrong org” and “not found.” The runtime resolver endpoint (/v1/runtime/agent-config/:agentId/pronunciation) is gated by the AGENT_RUNTIME_SHARED_SECRET header instead.