> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Configuration

> Configure an Anam persona's voice speed, volume, emotion, provider-specific options, and pronunciation dictionaries through Lab or the API.

You can configure how your persona's voice sounds — speed, volume, and emotion — via `voiceGenerationOptions` in the persona config. The available options depend on the provider and model of the configured voice. The example below uses a Cartesia Sonic 3.6 voice.

```javascript theme={"system"}
const personaConfig = {
  name: "Cara",
  avatarId: "071b0286-4cce-4808-bee2-e642f1062de3",
  avatarModel: "cara-4",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
  systemPrompt: "You are Cara, a helpful customer service representative.",
  voiceGenerationOptions: {
    speed: 1.2,
    volume: 0.8,
    emotion: "content"
  }
};
```

These settings can be set when creating or updating a persona, as well as when generating a session token. See the [API Reference](https://anam.ai/docs/api-reference/personas/create-persona.md) for details.

## Cartesia voices

For expressive speech, use Cartesia Sonic 3.6 (`sonic-3.6`). The following options are valid for Cartesia Sonic 3 voices, including Sonic 3.6:

| Option | Range | Description |
| - | - | - |
| `volume` | 0.5 – 2.0 | Multiplier to decrease or increase the volume of the original voice |
| `speed` | 0.6 – 1.5 | Multiplier to decrease or increase the speed of the original voice |
| `emotion` | string | Emotion to apply: `neutral`, `calm`, `angry`, `content`, `sad`, `scared` |

## ElevenLabs voices

### ElevenLabs v4

Anam supports `eleven_v4` and `eleven_v4_turbo`. Use `eleven_v4_turbo` for higher throughput and lower latency than `eleven_v4`.

Anam's built-in ElevenLabs voices (**Stock** in Lab) that used `eleven_v3_conversational` moved to `eleven_v4_turbo` on November 3, 2026. They kept their voice IDs, so personas that use them now speak with v4 Turbo unless their `voiceGenerationOptions` set a different `model`. Many of these voices also have a built-in Flash v2.5 version with the same name. To list the v4 Turbo ones in Lab, open the Voice tab's filters and set **Model** to **ElevenLabs v4 Turbo** and **Type** to **Stock**.

If you chose one of the separate v4 Turbo copies of built-in voices that Anam added in October 2026, its voice ID still works and resolves to the original voice. Saving the persona stores the original voice ID.

Select an Anam voice configured with either model and use its Anam voice ID as `voiceId`. The model name is not a voice ID. See [Custom Voices](https://anam.ai/docs/personas/voices/custom-voices.md) to import an ElevenLabs voice.

Both v4 models support these settings in `voiceGenerationOptions`:

| Option | Range | Description |
| - | - | - |
| `stability` | 0 – 1 | How much the voice varies between generations. Lower values introduce more emotional variation |
| `similarityBoost` | 0 – 1 | How closely the generated voice matches the original reference audio |

Do not send `speed`, `volume`, `emotion`, `style`, or `useSpeakerBoost` for v4 voices.

### ElevenLabs v3

ElevenLabs v3 supports expressive speech with inline cues, as v4 does. See [Director Notes](https://anam.ai/docs/personas/director-notes.md) for guidance on combining voice cues with avatar direction.

For ElevenLabs v3 voices, `stability` is the only supported voice setting in `voiceGenerationOptions`:

| Option | Range | Description |
| - | - | - |
| `stability` | 0 – 1 | How much the voice varies between generations. Lower values introduce more emotional variation |

The built-in voices that used `eleven_v3_conversational` now use `eleven_v4_turbo`. To keep a persona that uses one of them on v3, set `model` to `eleven_v3_conversational` in its `voiceGenerationOptions` and send only `stability` alongside it. To use v3 with another voice, [import an ElevenLabs voice](https://anam.ai/docs/personas/voices/custom-voices.md) with `eleven_v3_conversational` as its model; it is the default model for new ElevenLabs imports. Importing needs custom voice access.

Select an Anam voice configured with `eleven_v3_conversational` and use its Anam voice ID as `voiceId`. The model name is not a voice ID. Include only `stability` in the voice generation settings of your REST API persona configuration:

```json theme={"system"}
{
  "voiceId": "YOUR_ANAM_ELEVENLABS_V3_VOICE_ID",
  "voiceGenerationOptions": {
    "stability": 0.5
  }
}
```

Do not send `speed`, `volume`, `emotion`, `similarityBoost`, `style`, or `useSpeakerBoost` for v3 voices. The v1 and v2 options below do not apply to v3.

### ElevenLabs v1 and v2

The following options are valid for ElevenLabs `v1` and `v2` voices:

| Option | Range | Description |
| - | - | - |
| `stability` | 0 – 1 | How much the voice varies between generations. Lower values introduce more emotional variation |
| `similarityBoost` | 0 – 1 | How closely the generated voice matches the original reference audio |
| `speed` | 0.7 – 1.2 | Multiplier to decrease or increase the speed of the original voice |

For `v2` voices, these additional options are also available:

| Option | Type | Description |
| - | - | - |
| `useSpeakerBoost` | boolean | Boost similarity to the original speaker. May increase latency |
| `style` | 0 – 1 | How much the original speaker's style is amplified. Values other than 0 may increase latency |

## Pronunciation dictionaries

Use a pronunciation dictionary to control how your persona says names, brands, or technical terms. Each entry pairs a word or phrase with a **sounds like** spelling, an **International Phonetic Alphabet (IPA)** pronunciation, or both. For example, enter `Anam` as the source and `annum` as its "sounds-like" spelling. Captions and conversation history keep the original text.

You can create and manage dictionaries through [Anam Lab](https://lab.anam.ai) or the [pronunciation dictionaries API](https://anam.ai/docs/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary.md). Dictionaries belong to your organization and can be reused across personas and sessions.

IPA support depends on the voice's model. Cartesia Sonic 3 models, including Sonic 3.5 and 3.6, and ElevenLabs v3 and v4 models, including `eleven_v3_conversational`, `eleven_v4`, and `eleven_v4_turbo`, support IPA. When you provide both forms, Anam uses IPA on a model that supports it and the sounds-like spelling on other models.

**Provide both IPA and sounds like for each entry to enable the fallback.** Anam does not generate a sounds-like spelling from IPA. If you provide only IPA and the selected model does not support it, the entry is skipped and the word is spoken as written.

### Create and select a dictionary in Lab

**1. Open the dictionary workspace**

Open your persona in Anam Lab and select the **Voice** tab. Under **Pronunciation dictionary**, select **Manage dictionaries**.

**2. Create a dictionary**

Select **New**, enter a name, then select **Create dictionary**. Dictionaries belong to your organization and can be reused across personas.

**3. Add and preview entries**

Select **Add entry** and enter the source word or phrase. Fill in **Sounds like** for a respelling, **IPA** for a phonetic pronunciation, or both. To use IPA with a fallback for other models, fill in both fields on the same entry. Lab accepts IPA in Cartesia format, such as `<<ˈ|ɑ|n|ə|m>>`, and converts it for the selected provider.

Matching ignores capitalization by default; enable **Match case** to match only the spelling you entered.

For Cartesia or ElevenLabs voices, choose a preview voice and use the entry's play button to listen before saving. Previewing does not save your edits.

**4. Save and apply**

Select **Save**, then return to the **Voice** tab and confirm your dictionary is selected. **Publish** the persona to apply the selection to its saved configuration.

**Saving updates the dictionary in place for every existing persona that references it.** Each of those personas automatically uses the updated entries in new sessions; you do not need to reselect the dictionary or republish those personas. The dictionary has no separate publish step. Start a new session to test changes; running sessions keep the entries loaded when they started.

### Entry limits and matching

* A dictionary can contain up to 500 entries.
* Source text can contain up to 100 Unicode code points and cannot be blank; sounds-like spellings can contain up to 200. Neither can contain `[` or `]`. Provide at least one pronunciation form per entry.
* Entries match whole words or phrases: `cat` does not match inside `catalog`.
* Duplicate sources are rejected. Sources that differ only in capitalization are allowed when both use **Match case**.

To stop using a dictionary, select **None** in the persona's **Pronunciation dictionary** selector and publish the persona.

### Create and select a dictionary through the API

Use an API key from the organization that owns the dictionary. Restricted keys need `pronunciationDictionaries` read access to list or retrieve dictionaries and write access to create, import, update, or archive them. Full-access keys include these permissions.

Create a dictionary with `POST /v1/pronunciation-dictionaries`:

```bash theme={"system"}
curl --fail-with-body https://api.anam.ai/v1/pronunciation-dictionaries \
  -H "Authorization: Bearer $ANAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand names",
    "entries": [
      {
        "text": "Anam",
        "kind": "ipa",
        "pronunciation": "<<ˈ|ɑ|n|ə|m>>",
        "soundsLike": "annum"
      },
      {
        "text": "SQL",
        "pronunciation": "sequel",
        "caseSensitive": true
      }
    ]
  }'
```

The response is `201` and includes the dictionary's `id`, `name`, `revision`, timestamps, and `entries`. Omitted `kind` defaults to `sounds_like`; omitted `caseSensitive` defaults to `false`. Use `soundsLike` only on IPA entries to provide a fallback for models that do not support IPA.

Copy the returned `id` into `ANAM_DICTIONARY_ID`, and set `ANAM_PERSONA_ID` to a saved persona in the same organization. Pass the dictionary ID in `personaConfig.voiceGenerationOptions` when [creating a session token](https://anam.ai/docs/api-reference/sessions/create-session-token.md):

```bash theme={"system"}
curl --fail-with-body https://api.anam.ai/v1/auth/session-token \
  -H "Authorization: Bearer $ANAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"personaConfig\": {
      \"personaId\": \"$ANAM_PERSONA_ID\",
      \"voiceGenerationOptions\": {
        \"pronunciationDictionaryId\": \"$ANAM_DICTIONARY_ID\"
      }
    }
  }"
```

For an ephemeral persona, use the same field alongside your other persona configuration fields. For a saved persona, the dictionary replaces its saved selection for this session only. Omit the field to use the persona's saved dictionary. The latest saved entries are loaded when the session starts, rather than when the token is created.

## Changing voices

The `voiceGenerationOptions` are specific to the provider, model, and voice being used. When you change the `voiceId` for a persona, these options reset. Use the copy persona feature in Lab when experimenting with different voices to avoid losing your existing config.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.