From d813a6638dcd31cbf7d23a774a9901d19d3a8d6d Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Fri, 12 Jun 2026 11:42:06 -0700 Subject: [PATCH] docs: clarify pronunciation dictionaries support Vapi v1 voices only - Note that Vapi v2 (xAI/Grok) voices don't support pronunciation dictionaries yet, and link to xAI speech tags as the alternative. - Fix the Vapi built-in voice example: v2 + Elliot was invalid (Grok has no dictionary support and Elliot's v1 route is sonic-2); use v1 + Kylie (a v1 voice that maps to Cartesia sonic-3). - Small callout: the Cartesia dictionary option only appears in the dashboard once a sonic-3 (or newer) model is selected. Co-Authored-By: Claude Opus 4.8 (1M context) --- fern/assistants/pronunciation-dictionaries.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/fern/assistants/pronunciation-dictionaries.mdx b/fern/assistants/pronunciation-dictionaries.mdx index 328fbd3c5..7d2e28ea4 100644 --- a/fern/assistants/pronunciation-dictionaries.mdx +++ b/fern/assistants/pronunciation-dictionaries.mdx @@ -12,7 +12,11 @@ Pronunciation dictionaries are supported by the following voice providers: - **ElevenLabs** — phoneme rules (IPA and CMU Arpabet) and alias rules - **Cartesia** — "sounds-like" aliases and IPA notation (sonic-3 model only) -- **Vapi built-in voices** — pronunciation dictionaries via a unified locator +- **Vapi built-in voices** — pronunciation dictionaries via a unified locator (v1 voices only) + + + 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. + ## How Pronunciation Dictionaries Work @@ -88,7 +92,7 @@ Cartesia pronunciation dictionaries use a `text` and `alias` format. Each entry - **IPA notation**: Precise phonetic spelling wrapped in angle brackets (e.g., `"<<ˈ|v|ɑ|ˈ|p|i>>"`) - Cartesia pronunciation dictionaries are only available with the `sonic-3` model. + 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. ## Implementation @@ -242,8 +246,8 @@ Cartesia pronunciation dictionaries use a `text` and `alias` format. Each entry { "voice": { "provider": "vapi", - "version": 2, - "voiceId": "Elliot", + "version": 1, + "voiceId": "Kylie", "pronunciationDictionary": [ { "pronunciationDictId": "pdict_abc123"