ElevenLabs Text-to-Dialogue v3 / v4
Generate natural, expressive multi-speaker dialogue audio with ElevenLabs Eleven v3 or v4. Provide a sequence of dialogue turns, each with its own voice, and receive a single hosted audio file. Supports multiple languages.
Models
| Model | Stability | Output |
|---|---|---|
elevenlabs-text-to-dialogue-v3 | 0, 0.5, or 1; default 0.5 | MP3 |
elevenlabs-text-to-dialogue-v4 | Any number from 0 to 1; default 0.5 | MP3 |
Try v3 in the Playground or v4 in the Playground. Both models use the same request and task response format.
Generation uses the official Text-to-Dialogue API. See the Eleven v4 overview for the newer model's capabilities.
Pricing
Both models cost 24 credits per 1,000 Unicode characters, with no minimum charge. Sum all dialogue[].text characters, including spaces and audio tags, then round the request price to two decimal places. A supplementary Unicode character such as an emoji counts as one character.
| Characters | Base credits |
|---|---|
| 1 | 0.02 |
| 100 | 2.40 |
| 1,000 | 24.00 |
| 2,000 | 48.00 |
Your account pricing multiplier applies after the base price is rounded. The estimate endpoint returns your final charge before submission. Credits are pre-charged on submit and refunded for failed generation; completed tasks are not refunded.
Each request supports up to 2,000 total Unicode characters and 10 distinct voice IDs. Input validation happens before charging.
Create Task
curl -X POST https://api.aivideoapi.ai/v1/audio/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "elevenlabs-text-to-dialogue-v3",
"callback_url": "https://your-server.com/webhook",
"input": {
"dialogue": [
{ "text": "Hey! Did you finish the report?", "voice": "TX3LPaxmHKxFdv7VOQHJ" },
{ "text": "Almost — just adding the final numbers now.", "voice": "nPczCjzI2devNBz1zQrb" }
],
"stability": 0.5,
"language_code": "en"
}
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | elevenlabs-text-to-dialogue-v3 or elevenlabs-text-to-dialogue-v4 |
input | object | Yes | Generation parameters, see below |
callback_url | string | No | URL to receive task completion/failure notifications |
Input object
| Field | Type | Required | Description |
|---|---|---|---|
dialogue | array | Yes | Non-empty ordered list of { text, voice } turns; at most 2,000 Unicode characters in total and 10 distinct voices |
dialogue[].text | string | Yes | Non-empty spoken text; audio tags and whitespace count toward the character total |
dialogue[].voice | string | Yes | Voice ID; copy an ID from the verified catalog below |
stability | number | No | v3: 0, 0.5, or 1; v4: any number from 0 to 1. Default: 0.5 |
language_code | string | No | Optional language code such as en, zh, ja, or fr; omit or leave blank for automatic detection |
The output is a hosted MP3 audio file. Streaming and alternate output formats are not exposed by this endpoint.
Verified voices
The catalog contains verified voices, including official default voices, that are available to the official account. Other custom voices in the account are not automatically published. Names are display labels: always submit the voice ID. Voices can become unavailable; refresh the catalog before selecting a replacement.
| Name | Style | voice_id | Preview |
|---|---|---|---|
| Liam - Energetic, Social Media Creator | A young adult with energy and warmth - suitable for reels and shorts. | TX3LPaxmHKxFdv7VOQHJ | |
| Callum - Husky Trickster | Deceptively gravelly, yet unsettling edge. | N2lVS1w4EtoT3dr4eOWO | |
| Laura - Enthusiast, Quirky Attitude | This young adult female voice delivers sunny enthusiasm with a quirky attitude. | FGY2WhTYpPnrIDTdsKH5 | |
| Bella - Professional, Bright, Warm | This voice is warm, bright, and professional, characterized by a Standard American accent and a polished, narrative quality. It features a medium-high pitch with crisp diction and a deliberate, rhythmic pace that makes it highly intelligible and engaging for long-form listening. | hpp4J3VqNfWAUOO0d1Us | |
| Brian - Deep, Resonant and Comforting | Middle-aged man with a resonant and comforting tone. Great for narrations and advertisements. | nPczCjzI2devNBz1zQrb | |
| Roger - Laid-Back, Casual, Resonant | Easy going and perfect for casual conversations. | CwhRBWXzGAHq8TQ4Fs17 | |
| Sarah - Mature, Reassuring, Confident | Young adult woman with a confident and warm, mature quality and a reassuring, professional tone. | EXAVITQu4vr4xnSDxMaL | |
| Charlie - Deep, Confident, Energetic | A young Australian male with a confident and energetic voice. | IKne3meq5aSn9XLyUdCD | |
| George - Warm, Captivating Storyteller | Warm resonance that instantly captivates listeners. | JBFqnCBsd6RMkjVDRZzb | |
| River - Relaxed, Neutral, Informative | A relaxed, neutral voice ready for narrations or conversational projects. | SAz9YHcvj6GT2YYXdXww | |
| Harry - Fierce Warrior | An animated warrior ready to charge forward. | SOYHLrjzK2X1ezoPC6cr | |
| Alice - Clear, Engaging Educator | Clear and engaging, friendly woman with a British accent suitable for e-learning. | Xb7hH8MSUJpSbSDYk0k2 | |
| Matilda - Knowledgable, Professional | A professional woman with a pleasing alto pitch. Suitable for many use cases. | XrExE9yKIg1WjnnlVkGX | |
| Will - Relaxed Optimist | Conversational and laid back. | bIHbv24MWmeRgasZH58o | |
| Jessica - Playful, Bright, Warm | Young and popular, this playful American female voice is perfect for trendy content. | cgSgspJ2msm6clMCkdW9 | |
| Eric - Smooth, Trustworthy | A smooth tenor pitch from a man in his 40s - perfect for agentic use cases. | cjVigY5qzO86Huf0OWal | |
| Chris - Charming, Down-to-Earth | Natural and real, this down-to-earth voice is great across many use-cases. | iP95p4xoKVk53GoZ742B | |
| Daniel - Steady Broadcaster | A strong voice perfect for delivering a professional broadcast or news story. | onwK4e9ZLuTAKqWW03F9 | |
| Lily - Velvety Actress | Velvety British female voice delivers news and narrations with warmth and clarity. | pFZP5JQG7iQjIQuC4Bku | |
| Adam - Dominant, Firm | A bright tenor pitch that immediately cuts through. The delivery is brash and openly confident, speaking with unwavering certainty and a slightly aggressive self-assurance. | pNInz6obpgDQGcFmaJgB | |
| Bill - Wise, Mature, Balanced | Friendly and comforting voice ready to narrate your stories. | pqHfZKP75CvOlQylNhV4 |
Response
{
"code": 200,
"msg": "success",
"data": {
"taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
Estimate
Preview the credit cost without creating a task. The cost scales with the total character count of dialogue[].text.
curl -X POST https://api.aivideoapi.ai/v1/estimate \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "elevenlabs-text-to-dialogue-v3",
"input": {
"dialogue": [
{ "text": "Hello there!", "voice": "TX3LPaxmHKxFdv7VOQHJ" }
]
}
}'
Query Task
curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
-H "Authorization: Bearer sk-your-api-key"
Status transitions: pending -> processing -> completed or failed.
Completed
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"model": "elevenlabs-text-to-dialogue-v3",
"created_at": 1775383908,
"completed_at": 1775383956,
"output": {
"urls": [
"https://file.aivideoapi.ai/audio/2026/06/23/dialogue.mp3"
],
"metadata": {
"model": "elevenlabs-text-to-dialogue-v3"
}
}
}
Audio URLs are valid for 24 hours.
Failed
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "failed",
"model": "elevenlabs-text-to-dialogue-v3",
"created_at": 1775383908,
"error": {
"code": "upstream_error",
"message": "Generation failed"
}
}
When a task fails, pre-charged credits are automatically refunded.
Callback
Pass callback_url when creating the task. The system will automatically send a POST request to your URL when the task completes or fails. The format matches the query task response.
Error Codes
When a request fails, the API returns a JSON error response:
{
"error": {
"code": "insufficient_credits",
"message": "Your credit balance is too low. Please top up.",
"type": "billing_error"
}
}
Error Reference
| HTTP Status | Code | Type | Description |
|---|---|---|---|
| 400 | invalid_request | invalid_request_error | Missing or invalid parameters |
| 401 | invalid_api_key | authentication_error | API key is invalid, disabled, or deleted |
| 402 | insufficient_credits | billing_error | Credit balance too low, please top up |
| 403 | ip_not_allowed | permission_error | Request IP not in the key's allowlist |
| 404 | model_not_found | invalid_request_error | Model does not exist or is inactive |
| 404 | task_not_found | invalid_request_error | Task ID does not exist |
| 429 | rate_limit_exceeded | rate_limit_error | Too many requests, please slow down |
| 429 | spend_limit_exceeded | billing_error | Key spend limit reached (hourly/daily/total) |
| 500 | internal_error | api_error | Unexpected server error |
| 503 | upstream_error | upstream_error | Upstream AI provider returned an error |
Common Scenarios
invalid_request (400)
Returned when required fields are missing or invalid.
{
"error": {
"code": "invalid_request",
"message": "'model' is required.",
"type": "invalid_request_error"
}
}
insufficient_credits (402)
Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.
invalid_api_key (401)
Possible causes:
- The key does not start with
sk- - The key has been disabled or deleted
- The user account has been banned
upstream_error (503)
The upstream AI provider returned an error. This may happen when:
- The input contains sensitive or prohibited content
- The provider is temporarily unavailable
- The request parameters are not supported by the provider
Credits are automatically refunded when a task fails due to upstream errors.