Elevenlabs Voice

Overview

ElevenLabs provides text-to-speech voices for both in-app TTS and phone calls. Change the voice with the voice_config_update tool — it writes the voice to whichever TTS provider is currently active and pushes to the macOS app via SSE in one call:

Copy code
voice_config_update setting="tts_voice_id" value="<voice-id>"

The voice lives under the active provider, not always ElevenLabs. The config key depends on services.tts.provider: elevenlabs → services.tts.providers.elevenlabs.voiceId, vellum (managed) → services.tts.providers.vellum.model, deepgram → services.tts.providers.deepgram.model. The voice_config_update tool (and the assistant tts voice <id> CLI command) handle this routing for you. Do NOT assistant config set services.tts.providers.elevenlabs.voiceId ... blindly — on a managed (vellum) assistant that field is ignored, so the write "succeeds" but the voice never changes. See Setting the voice for the CLI fallback.

The tables below apply when the active provider is elevenlabs (BYO key) or managed vellum. On managed assistants they are the only ElevenLabs voices — the platform bills per rate-carded model and rejects anything else at synthesis (the write succeeds but the voice fails on the next turn), so don't offer library or cloned voices unless the elevenlabs provider is active with its own API key. With a BYO key (setup below) and elevenlabs active, any voice id works. Other BYO TTS providers (deepgram, xai, fish-audio, …) use their own voice/model identifiers — never write an ElevenLabs voice id to them; see Getting to an ElevenLabs voice from another provider.

Getting to an ElevenLabs voice from another provider

Check the active provider first: assistant config get services.tts.provider.

• Already on managed vellum? No provider change needed. The managed platform supports both ElevenLabs and Deepgram voices — services.tts.providers.vellum.model accepts either an ElevenLabs voice id or an Aura model id, so switching between them is just another voice_config_update call.
• On a BYO provider (e.g. deepgram) and the user wants an ElevenLabs voice? Two options — ask which they prefer. Switch with the voice_config_update tool, not raw assistant config set — the tool validates the switch (e.g. rejects vellum when no platform connection exists, which a raw config write would leave silently broken):
  1. Switch to managed vellum (voice_config_update setting="tts_provider" value="vellum") — no ElevenLabs key needed; requires a platform connection and bills managed credits. Bonus: they keep access to both the ElevenLabs and Deepgram catalogs.
  2. Switch to BYO elevenlabs (voice_config_update setting="tts_provider" value="elevenlabs") — requires an ElevenLabs API key (setup below); usage bills their ElevenLabs account directly.

After either switch, set the voice with voice_config_update as usual.

Choose a Voice

Pick a voice that matches your identity and the user's preferences. Offer to show the full list if they want to choose themselves.

Female voices

Male voices

These are ElevenLabs' current premade voices. Do not use retired legacy ids (Antoni, Josh, Arnold, Rachel, Charlotte, Amelia, …): ElevenLabs silently remaps them to different voices — synthesis succeeds but speaks as the wrong voice.

Setting the voice

Preferred — the tool. It writes to the active provider's voice field and pushes to the macOS app via SSE (ttsVoiceId) in one call:

Copy code
voice_config_update setting="tts_voice_id" value="<selected-voice-id>"

CLI fallback (only if the voice_config_update tool is unavailable). Use assistant tts voice, which routes to the active provider's config key for you — do not hand-write assistant config set services.tts.providers.elevenlabs.voiceId ...:

bashCopy code
assistant tts voice "<selected-voice-id>"

Setting services.tts.providers.elevenlabs.voiceId directly while the active provider is vellum (or any non-elevenlabs provider) is the #1 cause of "I changed the voice but it didn't change" — that field is ignored by the active provider, so the write reports success but nothing changes. If you must use config set, first check assistant config get services.tts.provider and write the matching key (vellum → services.tts.providers.vellum.model, deepgram → services.tts.providers.deepgram.model).

Verify it worked by reading back the key for the active provider, e.g. for a managed assistant:

bashCopy code
assistant config get services.tts.providers.vellum.model

The change hot-applies to the next voice turn (live voice and phone read the config fresh each turn).

Tell the user what voice you chose and why, but also offer to show all available voices so they can choose for themselves.

ElevenLabs API Key Setup

For advanced voice selection (browsing the full library, custom/cloned voices), the user needs an ElevenLabs API key. A free tier is available at https://elevenlabs.io.

To collect the API key securely:

bashCopy code
assistant credentials prompt --service elevenlabs --field api_key --label "ElevenLabs API Key"

Advanced Voice Selection (with API key)

Users with an ElevenLabs API key can go beyond the curated list above — only when the active provider is elevenlabs (BYO key). On managed vellum, stay with the curated voices: the platform only accepts its rate-carded subset, and an unoffered id is persisted successfully but fails on the next spoken turn.

Check for an existing key

bashCopy code
assistant credentials inspect --service elevenlabs --field api_key --json

Browse the voice library

bashCopy code
curl -s "https://api.elevenlabs.io/v2/voices?category=premade&page_size=50" \
  -H "xi-api-key: $(assistant credentials reveal --service elevenlabs --field api_key)" | python3 -m json.tool

Search for a specific style

bashCopy code
curl -s "https://api.elevenlabs.io/v2/voices?search=warm+female&page_size=10" \
  -H "xi-api-key: $(assistant credentials reveal --service elevenlabs --field api_key)" | python3 -m json.tool

Custom and cloned voices

If the user has created a custom voice or voice clone in their ElevenLabs account, they can use its voice ID directly. These voices work in both in-app TTS and phone calls.

Preview voices

Each voice in the API response includes a preview_url with an audio sample the user can listen to before deciding.

Set the chosen voice

After the user picks a voice from the library:

Copy code
voice_config_update setting="tts_voice_id" value="<selected-voice-id>"

Voice Tuning

Fine-tune how the selected voice sounds. These parameters apply to all ElevenLabs modes (in-app TTS and phone calls) when the active provider is elevenlabs — managed (vellum) synthesis does not read them:

bashCopy code
# Playback speed (0.7 = slower, 1.0 = normal, 1.2 = faster)
assistant config set services.tts.providers.elevenlabs.speed 1.0

# Stability (0.0 = more expressive/variable, 1.0 = more consistent/monotone)
assistant config set services.tts.providers.elevenlabs.stability 0.5

# Similarity boost (0.0 = more creative, 1.0 = closer to original voice)
assistant config set services.tts.providers.elevenlabs.similarityBoost 0.75

Lower stability makes the voice more expressive but less predictable - good for conversational calls. Higher stability is better for scripted or formal contexts.

Voice Model Tuning

By default, synthesis uses ElevenLabs' eleven_multilingual_v2 model. To use a different model (e.g. a lower-latency one), set a model ID:

bashCopy code
assistant config set services.tts.providers.elevenlabs.voiceModelId "eleven_flash_v2_5"

To clear and revert to the default model:

bashCopy code
assistant config set services.tts.providers.elevenlabs.voiceModelId ""