> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation dictionaries

> Manage custom pronunciations in Portal or as named pronunciation dictionaries through the API.

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

<CardGroup cols={1}>
  <Card title="Inline pronunciation" icon="spell-check" href="/tts/capabilities/custom-pronunciation">
    * **Manage in:** Synthesis text, using `/IPA/`
    * **Lifetime:** One request
    * **TTS behavior:** TTS speaks the inline IPA at that location
  </Card>

  <Card title="Workspace pronunciation dictionary" icon="book">
    * **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
  </Card>

  <Card title="Named pronunciation dictionaries" icon="list">
    * **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
  </Card>
</CardGroup>

<Note>
  The **Custom pronunciations** control inside TTS Playground is session-only. It rewrites matching terms to [inline IPA](/tts/capabilities/custom-pronunciation) before synthesis and does not add them to the workspace pronunciation dictionary.
</Note>

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

<Steps>
  <Step title="Open Pronunciations">
    Open a workspace in [Inworld Portal](https://platform.inworld.ai/). In the workspace sidebar, under **Configure**, select **Pronunciations**.

    If **Pronunciations** is not shown, the workspace pronunciation dictionary is not enabled.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Open TTS Playground">
    Open TTS Playground from the same workspace that owns the saved pronunciation.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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

<Warning>
  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.
</Warning>

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](/api-reference/pronunciationAPI/pronunciations/update-pronunciation-dictionary). Entries omitted from that list are deleted; an empty list clears the dictionary.

### Dictionary limits

| Value                      | Limit                                                        |
| -------------------------- | ------------------------------------------------------------ |
| Dictionary display name    | 1–64 Unicode code points; cannot be blank                    |
| Entries per dictionary     | 0–1,000                                                      |
| Encoded dictionary size    | 512 KiB                                                      |
| Headword                   | One replaceable lexical token, up to 128 Unicode code points |
| Phone sequence             | 1–64 supported tokens or aliases                             |
| Phone token                | Up to 16 Unicode code points                                 |
| Dictionaries per list page | 5                                                            |

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.

<CardGroup cols={2}>
  <Card title="Create a dictionary" icon="plus" href="/api-reference/pronunciationAPI/pronunciations/create-pronunciation-dictionary">
    Create a named dictionary with its complete validated contents.
  </Card>

  <Card title="List dictionaries" icon="list" href="/api-reference/pronunciationAPI/pronunciations/list-pronunciation-dictionaries">
    Discover dictionary resource names, contents, and current etags.
  </Card>
</CardGroup>