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:

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

Voice	Style	Voice ID
Sarah	Soft, young, approachable	EXAVITQu4vr4xnSDxMaL
Alice	Confident, British	Xb7hH8MSUJpSbSDYk0k2
Matilda	Warm, friendly, young	XrExE9yKIg1WjnnlVkGX
Lily	Warm, British	pFZP5JQG7iQjIQuC4Bku

Male voices

Voice	Style	Voice ID
Adam	Deep, middle-aged, professional	pNInz6obpgDQGcFmaJgB
Bill	Trustworthy, American	pqHfZKP75CvOlQylNhV4
George	Warm, British, distinguished	JBFqnCBsd6RMkjVDRZzb
Daniel	Authoritative, British	onwK4e9ZLuTAKqWW03F9
Charlie	Casual, Australian	IKne3meq5aSn9XLyUdCD
Liam	Young, articulate	TX3LPaxmHKxFdv7VOQHJ

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:

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 ...:

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:

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:

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

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

Browse the voice library

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

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:

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:

# 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:

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

To clear and revert to the default model:

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