Skip to main content
Pronunciation dictionaries associate written words with validated phoneme sequences and languages. They let you reuse custom pronunciations without placing IPA directly in every synthesis request. In addition to per-request inline IPA, Inworld provides two saved pronunciation-dictionary surfaces: a workspace dictionary managed in Portal and named dictionaries managed through the public API. They are separate resources with different TTS behavior.

​
Choose the right approach

Inline pronunciation

  • Manage in: Synthesis text, using /IPA/
  • Lifetime: One request
  • TTS behavior: TTS speaks the inline IPA at that location

Workspace pronunciation dictionary

  • Manage in: Pronunciations in Portal
  • Lifetime: Reusable within one workspace
  • TTS behavior: Portal automatically opts matching TTS-2 Playground requests into the workspace’s default dictionary

Named pronunciation dictionaries

  • Manage in: Pronunciation Dictionaries API
  • Lifetime: Reusable named resources within one workspace
  • TTS behavior: Management is available, but public TTS requests cannot select or apply a named dictionary yet
The Custom pronunciations control inside TTS Playground is session-only. It rewrites matching terms to inline IPA before synthesis and does not add them to the workspace pronunciation dictionary.

​
Manage the workspace pronunciation dictionary in Portal

Portal presents the workspace’s default pronunciation dictionary as individual saved entries. You do not need to create or name the dictionary.
1

Open Pronunciations

Open a workspace in Inworld Portal. In the workspace sidebar, under Configure, select Pronunciations.If Pronunciations is not shown, the workspace pronunciation dictionary is not enabled.
2

Start a pronunciation

Select Add pronunciation, enter exactly one word, and choose the language in which the pronunciation should apply. The same normalized word and language can appear only once.
3

Provide the pronunciation

Select Suggest IPA to start from a generated suggestion, or enter the phoneme symbols directly. The IPA palette contains the symbols supported for the selected language.If a microphone action is available, you can record how the word should sound and use the resulting IPA as an editable suggestion. The recording itself is not saved with the pronunciation.
4

Preview and save

Preview the pronunciation, adjust the phonemes if needed, and select Add. Portal validates the complete phone sequence for the selected language and may normalize supported aliases before saving it.
Use the pronunciation table to search by word or IPA, filter by language, preview an entry, edit its phone sequence, or delete it. Users without workspace asset-edit permission can view and preview entries but cannot create, edit, or delete them.

​
Apply the workspace pronunciation dictionary in TTS Playground

1

Open TTS Playground

Open TTS Playground from the same workspace that owns the saved pronunciation.
2

Choose a TTS-2 model

Select Realtime TTS-2 or Realtime TTS-2 Flash. The workspace pronunciation dictionary is not applied to older TTS models.
3

Set the language

Choose a concrete language that matches the dictionary entry, such as en-US. When the Playground indicates that custom pronunciations require a specific language, leaving Language set to Auto skips the workspace dictionary.
4

Generate with the original spelling

Enter the normal written word and generate speech. Portal automatically enables the workspace’s default pronunciation dictionary for both single-text and multi-turn TTS-2 generation.
Portal’s workspace pronunciation entries are not public named dictionaries. The public list and get methods do not return the workspace-default dictionary, and Portal does not list or edit named dictionaries created through the API.

​
Manage named dictionaries through the API

The Pronunciation Dictionaries API lets backend applications create and manage reusable, workspace-owned collections of pronunciation entries. A dictionary is one complete resource: create it in one request, retrieve or list it with all entries, and update its metadata or contents atomically. Use a Standard API key for the workspace that owns the dictionaries. Pronunciation dictionaries use the existing Voices permission: Voices Read permits list and get, while Voices Write permits create, update, and delete as well as reads. There is no separate Custom Pronunciations permission.
Named dictionaries can be managed through the public API, but production public TTS requests do not yet apply them. Continue using inline IPA or Portal’s workspace pronunciation dictionary for synthesis until named-dictionary selection is documented.
The API intentionally has no per-entry create, update, delete, import, or batch methods. A synchronous create or update accepts the complete dictionary, up to the limits below. To change entries, send the desired complete pronunciations list to Update a pronunciation dictionary. Entries omitted from that list are deleted; an empty list clears the dictionary.

​
Dictionary limits

Use a concrete canonical BCP-47 code such as en-US for each entry. auto is not accepted. Send phones as an array of symbols without slash delimiters; the service validates them for the selected language and can canonicalize supported aliases before saving.

​
Atomic validation and concurrency

Create and update validate every submitted entry before committing any change. Duplicate language/headword identities are rejected after language-aware lexical canonicalization, so spelling or casing variants that resolve to the same token cannot coexist in one dictionary. Every dictionary response contains an etag. Include the current value when updating or deleting a dictionary. A stale value returns HTTP 409 Conflict instead of overwriting a concurrent change; retrieve the resource again, reconcile the new state, and retry.

Create a dictionary

Create a named dictionary with its complete validated contents.

List dictionaries

Discover dictionary resource names, contents, and current etags.