[codex] add pronunciation dictionary guidance

developer-guide/core-features/fine-grained-control.mdx

@@ -14,8 +14,24 @@
   <AudioTranscript page="core-features-fine-grained-control" />
 </Visibility>
 
-<Card title="Try it live in the API playground" icon="flask" href="/api-reference/endpoint/openapi-v1/text-to-speech" horizontal>
-  Put your phoneme or paralanguage tags into the `text` field and send a real request to hear the result.
+<Card
+  title="Try it live in the API playground"
+  icon="flask"
+  href="/api-reference/endpoint/openapi-v1/text-to-speech"
+  horizontal
+>
+  Put your phoneme or paralanguage tags into the `text` field and send a real
+  request to hear the result.
+</Card>
+
+<Card
+  title="Use pronunciation dictionaries"
+  icon="book-open"
+  href="/developer-guide/core-features/fine-grained-control/pronunciation-dictionaries"
+  horizontal
+>
+  Reuse pronunciation rules for names, brands, acronyms, and domain terms across
+  many TTS requests.
 </Card>
 
 ## Getting Started
@@ -88,9 +104,9 @@
 <|phoneme_start|>ha0shi1ga0<|phoneme_end|>見えます。
 ```
 
 ## Paralanguage
 
 Paralanguage controls allow you to add natural speech elements and pauses to make the generated speech sound more human-like. There are two main types of controls:
 
 ### Pause Words
 
@@ -121,7 +137,7 @@
 I am, um, an (break) engineer.
 ```
 
 You can combine paralanguage and phoneme control in the same text:
 
 ```text
 I am, um, an (break) <|phoneme_start|>EH1 N JH AH0 N IH1 R<|phoneme_end|>.

developer-guide/core-features/fine-grained-control/pronunciation-dictionaries.mdx

@@ -0,0 +1,132 @@
+---
+title: "Pronunciation Dictionaries"
+description: "Reuse pronunciation rules for names, brands, acronyms, and domain terms"
+icon: "book-open"
+---
+
+## Overview
+
+Pronunciation dictionaries are for reusable pronunciation fixes. Use them when the same names, brands, acronyms, product terms, or domain-specific phrases appear across many TTS requests and you want consistent output without adding phoneme tags into every script.
+
+For a one-off correction, inline phoneme tags in `text` are usually faster. For repeated corrections, put the written form in a dictionary `key` and the desired phoneme form in `value`.
+
+<Note>
+  A pronunciation dictionary is not a translation dictionary or a general text
+  normalizer. It only tells synthesis how a matched written form should sound.
+</Note>
+
+## 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.
+- Domain scripts where the same word list is reused across batches, agents, 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.
+
+## Item Shape
+
+Each dictionary item has this shape:
+
+```json
+{
+  "key": "Kubernetes",
+  "value": "K UW2 B ER0 N EH1 T IY0 Z",
+  "case_sensitive": false
+}
+```
+
+`key` is the exact written text to match in the TTS input. Use the same spelling, script, spacing, and punctuation that you expect to appear in the request text. Prefer leaving punctuation out of the key unless it is part of the term itself.
+
+`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 | Recommended value format                 | Example                     |
+| -------- | ---------------------------------------- | --------------------------- |
+| English  | CMU Arpabet                              | `K UW2 B ER0 N EH1 T IY0 Z` |
+| Chinese  | Tone-number pinyin in reading order      | `chong2 qing4`              |
+| Japanese | OpenJTalk-style romaji with pitch digits | `ha0shi1ga0`                |
+
+`case_sensitive` defaults to `false`. In managed dictionary versions, duplicate detection treats keys that only differ by case as the same rule when `case_sensitive` is `false`. Set it to `true` when `Fish` and `fish` must be separate entries.
+
+## Inline Dictionaries
+
+Pass inline dictionaries directly in a TTS request when the rules are request-specific:
+
+```json
+{
+  "text": "Our Kubernetes service reads SQL from DynamoDB.",
+  "reference_id": "model-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.
+
+## Managed Dictionaries
+
+Use managed dictionaries when the same rules should be reused across requests. A managed dictionary is saved on the platform, then referenced by dictionary id and immutable version id:
+
+```json
+{
+  "text": "Welcome to the Acme onboarding flow.",
+  "reference_id": "model-id",
+  "pronunciation_dictionary": [
+    {
+      "id": "dictionary_id",
+      "version": "version_id"
+    }
+  ]
+}
+```
+
+Always send an explicit `version`. There is no implicit latest version in TTS requests, which keeps synthesis reproducible after a dictionary is edited.
+
+Treat dictionary ids and version ids as sensitive when the entries are sensitive. A version is designed to be read by id and version id so edge services can resolve it during synthesis.
+
+## Processing Rules
+
+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`.
+
+Processing works like this:
+
+1. The API validates the request. A request can include up to 3 dictionaries. Each dictionary can include up to 5000 items. A key can be 1-256 characters and a value can be 1-1024 characters.
+2. For inline dictionaries, the API preserves item order and merges all items into one flat list.
+3. For managed references, the API fetches each `id` and `version`, uses a read-through cache, and merges resolved items in the order you provided. If a referenced dictionary cannot be fetched, that reference is skipped and synthesis continues.
+4. Empty items and items containing phoneme marker tokens are rejected or dropped before synthesis.
+5. The merged dictionary is sent to the inference engine. The engine matches each `key` according to `case_sensitive`, wraps `value` as a phoneme block, and applies the result during synthesis.
+
+Ordering matters when multiple dictionaries contain the same key. Put the entry that should win earlier in the list.
+
+## 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.

docs.json

@@ -38,6 +38,7 @@
                     "icon": "sliders",
                     "pages": [
                       "developer-guide/core-features/fine-grained-control",
+                      "developer-guide/core-features/fine-grained-control/pronunciation-dictionaries",
                       "developer-guide/core-features/fine-grained-control/english",
                       "developer-guide/core-features/fine-grained-control/chinese",
                       "developer-guide/core-features/fine-grained-control/japanese"

llms.txt

@@ -47,6 +47,7 @@
 - [Creating Voice Models](https://docs.fish.audio/developer-guide/core-features/creating-models.md): Learn how to create custom voice models with Fish Audio.
 - [Emotion Control](https://docs.fish.audio/developer-guide/core-features/emotions.md): Add natural emotions and expressions to your AI-generated speech.
 - [Fine-grained Control](https://docs.fish.audio/developer-guide/core-features/fine-grained-control.md): Advanced control over speech generation.
+- [Pronunciation Dictionaries](https://docs.fish.audio/developer-guide/core-features/fine-grained-control/pronunciation-dictionaries.md): Reuse pronunciation rules for names, brands, acronyms, and domain terms.
 - [English Phoneme Control](https://docs.fish.audio/developer-guide/core-features/fine-grained-control/english.md): Control English pronunciation with CMU Arpabet.
 - [Chinese Phoneme Control](https://docs.fish.audio/developer-guide/core-features/fine-grained-control/chinese.md): Control Chinese pronunciation with tone-number pinyin.
 - [Japanese Phoneme Control](https://docs.fish.audio/developer-guide/core-features/fine-grained-control/japanese.md): Control Japanese pronunciation with romaji phonemes and pitch accent markers.