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, 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 endpoint versus read yesterday.
  • Abbreviations, symbols, or spellings that should be spoken as other words, such as Dr. read as Doctor or km/h read as kilometers per hour. Use an alias rule for these.
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. 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.
  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. 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:
Text imports create phoneme rules and 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.

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 an id:
The 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_id to the dictionary’s current latest_version_id (null for 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:
Alias values go through the same text normalization as the rest of the request, so numbers, dates, and symbols in a value are read the same way they would be in the input text.

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 a phoneme 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 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. 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 key as the listener-facing surface form, not as a regex or pattern.
  • For phoneme rules, write value as phonemes only, without marker tokens.
  • For alias rules, write value as 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.