> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fish.audio/llms.txt
> Use this file to discover all available pages before exploring further.
# Pronunciation Dictionaries
> Create, preview, and publish pronunciation dictionaries in the web app and use them in TTS requests
## Overview
Pronunciation dictionaries are available in the [Fish Audio web app](https://fish.audio/app/pronunciation-dictionary) and the [TTS API](/api-reference/endpoint/openapi-v1/text-to-speech). Use them when the same names, brands, acronyms, or technical terms appear across many requests and you want consistent pronunciation without adding phoneme tags to every script.
Create and publish a dictionary in the web app, then reference its dictionary ID and version ID in your TTS requests. For rules that only apply to one request, send an [inline dictionary](#inline-dictionaries) instead.
Create rules, preview how they sound, and publish reusable versions.
## When To Use It
Use a pronunciation dictionary for:
* Product names, brand names, people names, or place names that are often misread.
* Acronyms and technical terms such as `SQL`, `Kubernetes`, or internal project names.
* Scripts where the same word list is reused across batches or episodes.
* Homographs when a larger phrase can remove ambiguity, such as `read endpoint` versus `read yesterday`.
Avoid broad entries for common words unless every occurrence should be read the same way. If pronunciation depends on context, use a longer phrase as the key or place a [phoneme tag](/developer-guide/core-features/fine-grained-control#phoneme-control) directly in the text.
## Create and Publish a Dictionary
1. Sign in to [Pronunciation dictionary](https://fish.audio/app/pronunciation-dictionary) and select **New Dictionary**. Enter a name and an optional description, then select **Create Dictionary**.
2. Select **Add a new rule**. Enter the written word or phrase in **Input** and its phoneme pronunciation in **Output**. Turn on **Case sensitive** if capitalization should affect matching.
3. Select a voice and model, then use **Play preview** on a rule to hear its pronunciation. Previewing a rule does not publish your edits.
4. Select **Publish New Version** to save the rules as an immutable version.
5. Open the dictionary's **More actions** menu and copy **Dictionary ID** and **Latest Version ID**. Use these as `id` and `version` in the [TTS request below](#use-a-published-dictionary).
Unpublished edits do not change a published version. After publishing an
update, change the `version` in your TTS request to use it. Requests pinned to
an older version keep using that version's rules.
Open **Version history** to inspect published versions and compare their rules.
### Import and Export Rules
You can upload an existing `.pls`, `.xml`, or `.txt` file when creating a dictionary, or use **Import PLS** in the editor. Imported pronunciations must use the [phoneme formats below](#write-pronunciation-rules); importing a file does not convert IPA to Fish Audio phonemes.
For a `.txt` file, put one rule on each line, separating the input and output with a comma or tab:
```text theme={null}
Kubernetes,K UW2 B ER0 N EH1 T IY0 Z
SQL,EH1 S K Y UW1 EH1 L
```
Text imports default to case-insensitive matching. Review the rules, preview them, and publish any changes before using the version in TTS. To export a published dictionary as a PLS file, select **Download** from its **More actions** menu.
## Write Pronunciation Rules
Each rule maps the written text (`key`, shown as **Input** in the web app) to a phoneme pronunciation (`value`, shown as **Output**):
```json theme={null}
{
"key": "Kubernetes",
"value": "K UW2 B ER0 N EH1 T IY0 Z",
"case_sensitive": false
}
```
`key` is a literal substring to match in the TTS input, not a regular expression or a whole-word pattern. Use the spelling, spacing, and punctuation you expect in the text. A short key can also match inside a longer word, so include enough context to avoid unintended replacements.
`value` is the phoneme string that should replace the key during synthesis. Do not include `<|phoneme_start|>` or `<|phoneme_end|>`; the synthesis pipeline wraps dictionary values internally.
Use the same phoneme notation as manual phoneme control:
| Language | Value format | Example |
| ------------------------------------------------------------------------ | ---------------------------------------- | --------------------------- |
| [English](/developer-guide/core-features/fine-grained-control/english) | CMU Arpabet | `K UW2 B ER0 N EH1 T IY0 Z` |
| [Chinese](/developer-guide/core-features/fine-grained-control/chinese) | Tone-number pinyin | `chong2` |
| [Japanese](/developer-guide/core-features/fine-grained-control/japanese) | OpenJTalk-style romaji with pitch digits | `ha0shi1ga0` |
`case_sensitive` defaults to `false`, which ignores ASCII capitalization when matching. Set it to `true` when a rule should only match the exact capitalization you entered. Managed dictionaries reject duplicate keys; when case sensitivity is off, keys that differ only by case count as duplicates.
## Use a Published Dictionary
After publishing a dictionary, pass its dictionary ID and version ID in `pronunciation_dictionary`. Set `FISH_API_KEY` to your [API key](/developer-guide/getting-started/api-key), and replace the placeholder IDs with the values copied from the web app:
```bash theme={null}
curl --request POST https://api.fish.audio/v1/tts \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--header "model: s2-pro" \
--data '{
"text": "Our Kubernetes service reads SQL.",
"reference_id": "YOUR_VOICE_ID",
"format": "mp3",
"pronunciation_dictionary": [
{
"id": "YOUR_DICTIONARY_ID",
"version": "YOUR_VERSION_ID"
}
]
}' \
--output speech.mp3
```
`reference_id` selects the voice; it is separate from the dictionary ID. Find a voice ID in the [Voice Library](https://fish.audio/app/discovery).
Always send an explicit `version`. Use the copied version ID, not the display number such as `V1` or the string `latest`. Publishing a new version does not automatically update existing requests.
## Inline Dictionaries
Pass inline dictionaries directly in a TTS request when the rules are request-specific:
```json theme={null}
{
"text": "Our Kubernetes service reads SQL from DynamoDB.",
"reference_id": "YOUR_VOICE_ID",
"pronunciation_dictionary": [
{
"items": [
{
"key": "Kubernetes",
"value": "K UW2 B ER0 N EH1 T IY0 Z",
"case_sensitive": false
},
{
"key": "SQL",
"value": "EH1 S K Y UW1 EH1 L",
"case_sensitive": true
},
{
"key": "DynamoDB",
"value": "D AY1 N AH0 M OW0 D IY1 B IY1",
"case_sensitive": false
}
]
}
]
}
```
Inline dictionaries are best for temporary overrides, generated scripts, or per-customer terms that you do not need to manage as reusable platform resources.
## Request Limits and Matching
The TTS API accepts either managed references or inline dictionaries in one request. Do not mix both forms in the same `pronunciation_dictionary` array.
Send pronunciation dictionaries with `application/json` or `application/msgpack`. Nested dictionary arrays are not representable in `multipart/form-data`.
| Limit | Maximum |
| ------------------------ | ------- |
| Dictionaries per request | 3 |
| Rules per dictionary | 5,000 |
| Characters per `key` | 256 |
| Characters per `value` | 1,024 |
Keys and values must be nonempty and must not contain `<|phoneme_start|>` or `<|phoneme_end|>` markers.
Dictionaries are combined in the order you send them. When the same key appears more than once, the first entry wins. For overlapping matches, the earliest match in the text wins; if matches start at the same position, the longest key wins. Replacements are applied during synthesis, and replacement values are not matched again.
If a dictionary ID or version ID cannot be resolved, the API skips that
reference and continues synthesis. A successful audio response does not prove
that the dictionary was applied. Check the IDs and listen to representative
text when testing a new version.
## Practical Tips
* Write `key` as the listener-facing surface form, not as a regex or pattern.
* Write `value` as phonemes only, without marker tokens.
* Use narrow keys for context-sensitive words; use phrase keys when a single word is ambiguous.
* Keep dictionaries scoped by product, customer, language, or domain so broad rules do not surprise unrelated scripts.
* Test a new dictionary version with representative text before using it in production traffic.