Skip to content

Commit 142b2ce

Browse files
authored
docs: clarify pronunciation dictionaries support Vapi v1 voices only (#1071)
## Description Problem: The pronunciation dictionaries page never said which Vapi voices support the feature, and its example used `version: 2` (a Grok voice) with a pronunciation dictionary — a config the backend actually rejects. This clarifies that pronunciation dictionaries work on **Vapi v1 voices only**, points v2 (Grok) users to speech tags instead, and fixes the misleading example. - Added a note that pronunciation dictionaries are supported on Vapi **v1** voices only. Vapi **v2** voices are powered by xAI's Grok model and don't support them yet — with a link to [xAI speech tags](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech#speech-tags) as the alternative. - Fixed the Vapi built-in voice example: `version: 2` + `Elliot` → `version: 1` + `Kylie` (a v1 voice that maps to Cartesia `sonic-3`, so it genuinely supports a dictionary). - Small callout: the Cartesia dictionary option only appears in the dashboard once a `sonic-3` (or newer) model is selected. File: `fern/assistants/pronunciation-dictionaries.mdx`. No navigation changes. Related: [PRISM-475](https://linear.app/vapi/issue/PRISM-475/platform-cartesia-pronunciation-dictionary-dashboard-ui-surface) (pronunciation dictionary dashboard work). Companion to the dashboard link fix in VapiAI/vapi#13221. ## Testing Steps - [x] `fern check` — 0 errors (5 pre-existing config warnings, none on this page) - [x] JSON example valid (the edited Vapi voice config parses) - [x] No new internal links (only added link is the external xAI speech-tags URL) - [x] Example cross-checked against source — voice version mappings in `libs/core/.../voice.types/vapi.types.ts` (Kylie → v1 Cartesia `sonic-3`; v2 = xAI/Grok, no dictionary support) - [x] Style: active voice, present tense, no marketing language - [ ] Confirm the v1/v2 note and Cartesia callout render in the preview deployment
1 parent 636ec01 commit 142b2ce

1 file changed

Lines changed: 8 additions & 4 deletions

File tree

fern/assistants/pronunciation-dictionaries.mdx

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@ Pronunciation dictionaries are supported by the following voice providers:
1212

1313
- **ElevenLabs** — phoneme rules (IPA and CMU Arpabet) and alias rules
1414
- **Cartesia** — "sounds-like" aliases and IPA notation (sonic-3 model only)
15-
- **Vapi built-in voices** — pronunciation dictionaries via a unified locator
15+
- **Vapi built-in voices** — pronunciation dictionaries via a unified locator (v1 voices only)
16+
17+
<Note>
18+
Pronunciation dictionaries are supported on **Vapi v1 voices** only. Vapi **v2** voices are powered by xAI's Grok model, which doesn't support pronunciation dictionaries yet. For v2 voices, use [speech tags](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech#speech-tags) to control pronunciation and delivery inline in your text instead.
19+
</Note>
1620

1721
## How Pronunciation Dictionaries Work
1822

@@ -88,7 +92,7 @@ Cartesia pronunciation dictionaries use a `text` and `alias` format. Each entry
8892
- **IPA notation**: Precise phonetic spelling wrapped in angle brackets (e.g., `"<<ˈ|v|ɑ|ˈ|p|i>>"`)
8993

9094
<Note>
91-
Cartesia pronunciation dictionaries are only available with the `sonic-3` model.
95+
Cartesia pronunciation dictionaries are only available with the `sonic-3` (or newer) model. In the dashboard, the pronunciation dictionary option only appears once you select a supported model.
9296
</Note>
9397

9498
## Implementation
@@ -242,8 +246,8 @@ Cartesia pronunciation dictionaries use a `text` and `alias` format. Each entry
242246
{
243247
"voice": {
244248
"provider": "vapi",
245-
"version": 2,
246-
"voiceId": "Elliot",
249+
"version": 1,
250+
"voiceId": "Kylie",
247251
"pronunciationDictionary": [
248252
{
249253
"pronunciationDictId": "pdict_abc123"

0 commit comments

Comments
 (0)