Overview
Pronunciation dictionaries are available in the Fish Audio web app and the TTS API. 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, or when a term should always be read as different text. Create and publish a dictionary in the web app or with the API, then reference its dictionary ID and version ID in your TTS requests. For rules that only apply to one request, send an inline dictionary instead.Open pronunciation dictionaries
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 endpointversusread yesterday. - Abbreviations, symbols, or spellings that should be spoken as other words, such as
Dr.read asDoctororkm/hread askilometers per hour. Use an alias rule for these.
Create and Publish a Dictionary
- Sign in to Pronunciation dictionary and select New Dictionary. Enter a name and an optional description, then select Create Dictionary.
- Select Add a new rule. Enter the written word or phrase in Input. Choose the rule type: Phoneme to enter its phoneme pronunciation in Output, or Alias to enter the replacement text that should be spoken instead. Turn on Case sensitive if capitalization should affect matching.
- Select a voice and model, then use Play preview on a rule to hear its pronunciation. Previewing a rule does not publish your edits.
- Select Publish New Version to save the rules as an immutable version.
- Open the dictionary’s More actions menu and copy Dictionary ID and Latest Version ID. Use these as
idandversionin the TTS request below.
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.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. In a PLS file, <phoneme> entries become phoneme rules and <alias> entries become alias rules. PLS files exported from Fish Audio before alias rules existed stored every rule as <alias>; they still import as phoneme rules. Imported pronunciations must use one of the phoneme formats below. IPA values are imported as written, with one pair of surrounding / delimiters removed; importing a file does not convert between formats, so IPA rules only take effect on models that accept IPA.
For a .txt file, put one rule on each line, separating the input and output with a comma or tab:
Manage Dictionaries with the API
Everything the web app does with dictionaries is also available through the pronunciation dictionary API, authenticated with your API key. An API key works on the dictionaries of the team it belongs to. Create a dictionary, then publish its first version. The response of each call includes anid:
id of the dictionary and the id of the new version are the id and version you send in TTS requests.
- A version holds the complete rule list. To change rules, publish a new version with every rule it should contain; published versions never change.
- Set
expected_latest_version_idto the dictionary’s currentlatest_version_id(nullfor the first version). If someone published in the meantime, the request returns 409: fetch the new latest version, merge its rules with your changes, and publish again. - Deleting a version is not possible for the latest version of a dictionary.
Write Pronunciation Rules
Each rule maps the written text (key, shown as Input in the web app) to a value (shown as Output). The rule’s type decides what the value means:
Rule Types
type is optional and defaults to phoneme, so rules created before alias rules existed keep working unchanged. Use alias when a term should be spoken as different words rather than with a specific pronunciation:
Keys
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.
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.
Phoneme Values
For aphoneme rule, value is the phoneme string that should replace the key during synthesis. Do not include <|phoneme_start|> or <|phoneme_end|>; the synthesis pipeline wraps phoneme values internally.
Use the same phoneme notation as manual phoneme control:
Use a Published Dictionary
After publishing a dictionary, pass its dictionary ID and version ID inpronunciation_dictionary. Set FISH_API_KEY to your API key, and replace the placeholder IDs with the values copied from the web app:
reference_id selects the voice; it is separate from the dictionary ID. Find a voice ID in the Voice Library.
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:Request Limits and Matching
The TTS API accepts either managed references or inline dictionaries in one request. Do not mix both forms in the samepronunciation_dictionary array.
Send pronunciation dictionaries with application/json or application/msgpack. Nested dictionary arrays are not representable in multipart/form-data.
Keys and values must be nonempty and must not contain
<|phoneme_start|> or <|phoneme_end|> markers. Alias rules have extra limits: an alias key cannot start or end with whitespace and cannot contain control characters, <|, |>, (, ), [, or ], and an alias value cannot contain <| or |>.
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. Phoneme and alias rules are matched together under these rules, regardless of type. Replacements are applied during synthesis, and replacement values are not matched again, so an alias value that contains another key is not replaced a second time.
Alias rules change the billed length. Usage is billed on the text that is actually synthesized, with alias replacements applied: an alias that expands a short key into a longer value is billed for the longer text, and an alias that shortens the text is billed for the shorter text. Keys that are not replaced, for example because a longer key matched first, do not change the billed length. Phoneme rules never change the billed length.
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
keyas the listener-facing surface form, not as a regex or pattern. - For phoneme rules, write
valueas phonemes only, without marker tokens. - For alias rules, write
valueas the text a listener should hear; use a phoneme rule when you need to control how a word is pronounced. - 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.

