ElevenLabs Voice Design 🎙️

Deep-dive reference for the /v1/text-to-voice/design endpoint and related voice creation flow.

🧠 Model IDs (Voice Design vs TTS)

Context	Model ID	Audio Tags	Notes
TTS (text-to-speech)	eleven_v3	✅ Yes	Standard TTS endpoint
Voice Design	eleven_ttv_v3	✅ Yes	⚠️ Different ID than TTS!
Voice Design (old)	eleven_multilingual_ttv_v2	❌ No	Default if model_id omitted — reads tags literally

⚠️ Critical: eleven_v3 ≠ eleven_ttv_v3 — different model IDs for different endpoints!

🔗 Voice Design Flow (3 steps)

1. POST /v1/text-to-voice/design     → generates previews (base64 audio + generated_voice_id)
2. Listen & pick favorite preview
3. POST /v1/text-to-voice/create     → saves voice to library using generated_voice_id

Alternative legacy endpoint: POST /v1/text-to-voice/create-previews (similar but fewer params)

📡 POST /v1/text-to-voice/design

Design a voice via a text prompt. Returns voice previews with generated_voice_id + base64 audio.

Required

Param	Type	Description
voice_description	string	Voice character description (age, tone, accent, pacing)

Recommended

Param	Type	Default	Description
model_id	string	eleven_multilingual_ttv_v2	Use eleven_ttv_v3 for V3 audio tags!
text	string	—	Preview text (100-1000 chars)
guidance_scale	float	~30	Prompt adherence [0-100]. Lower = creative, higher = strict
loudness	float	0	Volume [-1, 1]. 0 ≈ -24 LUFS

Optional

Param	Type	Default	Description
output_format	string	mp3_22050_32	Audio format (e.g. mp3_44100_128)
should_enhance	bool	false	AI-enhance voice description for better results
quality	float	—	Higher = better output, less variety
seed	int	random	Reproducible generation (same seed + inputs = same voice)
auto_generate_text	bool	false	Auto-generate preview text from description
stream_previews	bool	false	Return IDs only, stream via /v1/text-to-voice/:id/stream
reference_audio_base_64	string	—	Reference audio (V3 model only)
prompt_strength	float	—	Prompt vs reference balance [0-1] (V3 only)

Example Request

{
  "voice_description": "A warm British man in his 30s, conversational and relatable",
  "text": "[laughs] See, that is the thing about innovation...",
  "model_id": "eleven_ttv_v3",
  "guidance_scale": 35,
  "loudness": 0,
  "output_format": "mp3_44100_128"
}

Response

{
  "previews": [
    {
      "audio_base_64": "<base64 mp3>",
      "generated_voice_id": "abc123...",
      "media_type": "audio/mpeg",
      "duration_secs": 8.5
    }
  ]
}

💾 POST /v1/text-to-voice/create

Save a designed voice to your library.

{
  "voice_name": "British Entrepreneur",
  "voice_description": "Warm British conversational voice",
  "generated_voice_id": "abc123..."
}

🏷️ V3 Audio Tags (work in both TTS and Voice Design)

Emotions: [laughs] [sighs] [giggles] [crying] [curious] [mischievously] Delivery: [whispers] [shouts] [sarcastic] [excited] [sad] [angry] Pacing: [slowly] [quickly] [long pause] Reactions: [clears throat] [light chuckle] [gasps] Sounds: [door slam] [rain softly in the background] [crowd cheering]

Tags go inline with text in lowercase square brackets.

🎯 Prompting Best Practices (Voice Description)

Follow: age + tone/timbre + gender + accent + pacing

"An elderly man with a deep, warm, gravelly voice. Speaks slowly with a neutral accent."
"A high-energy female sports commentator with a thick British accent, very quick pace."

Tips:

• Longer, detailed prompts → lower guidance_scale (15-30)
• Short prompts → higher guidance_scale (35-50) or enable should_enhance
• Include audio quality hints: “Perfect audio quality” / “Studio-quality recording”
• Guidance > 60 can sound robotic — sweet spot is 20-40

⚠️ Common Pitfalls

Pitfall	Symptom	Fix
Missing model_id	Tags read aloud literally	Add model_id: "eleven_ttv_v3"
Using eleven_v3 in design	API error	Use eleven_ttv_v3 (different ID!)
Text < 100 chars	400 error	Pad preview text to 100+ chars
Text > 1000 chars	400 error	Trim or chunk text
Guidance too high (>60)	Robotic output	Lower to 20-40 range

🔄 Related Endpoints

Endpoint	Purpose
POST /v1/text-to-voice/design	Generate voice previews (current)
POST /v1/text-to-voice/create-previews	Generate previews (legacy, no model_id)
POST /v1/text-to-voice/create	Save preview to library
GET /v1/text-to-voice/:id/stream	Stream a preview by ID
POST /v1/text-to-voice/:voice_id/remix	Remix existing voice
POST /v1/text-to-speech/:voice_id	TTS with saved voice