Skip to main content

​
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. 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 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 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 directly in the text.

​
Create and Publish a Dictionary

  1. Sign in to 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.
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; 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 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):
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: 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, 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:
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. 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.