ElevenLabs Text-to-Dialogue v3 / v4
使用 ElevenLabs Eleven v3 或 v4 生成自然、富有表现力的多角色对话音频。传入一组对话轮次,每轮指定各自的声音(voice),即可得到一段托管的音频文件。支持多语言。
模型
| 模型名称 | 稳定性 | 输出 |
|---|---|---|
elevenlabs-text-to-dialogue-v3 | 0、0.5 或 1,默认 0.5 | MP3 |
elevenlabs-text-to-dialogue-v4 | 0 到 1 之间任意数值,默认 0.5 | MP3 |
可在 Playground 体验 v3 或 v4。两个模型使用相同的请求与任务响应格式。
生成请求直接调用 官方 Text-to-Dialogue API。新版模型能力参见 Eleven v4 官方介绍。
计费
两个模型均为 每 1,000 个 Unicode 字符 24 积分,无最低消费。统计所有 dialogue[].text 的字符数,包括空格、换行和音频标签,按一次请求的总价四舍五入到两位小数。Emoji 等补充平面 Unicode 字符按一个字符计算。
| 字符数 | 基础积分 |
|---|---|
| 1 | 0.02 |
| 100 | 2.40 |
| 1,000 | 24.00 |
| 2,000 | 48.00 |
基础价取两位小数后,再应用账户定价倍率。可使用 Estimate 接口 获取最终扣费金额。提交时预扣积分,生成失败退款;任务成功后不会退款。
单次请求最多 2,000 个 Unicode 字符、10 个不同 voice ID。参数校验在扣费前完成。
创建任务
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": "嘿!报告写完了吗?", "voice": "TX3LPaxmHKxFdv7VOQHJ" },
{ "text": "差不多了,正在补最后的数据。", "voice": "nPczCjzI2devNBz1zQrb" }
],
"stability": 0.5,
"language_code": "zh"
}
}'
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | elevenlabs-text-to-dialogue-v3 或 elevenlabs-text-to-dialogue-v4 |
input | object | 是 | 生成参数,见下 |
callback_url | string | 否 | 任务完成/失败时接收通知的回调地址 |
Input 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
dialogue | array | 是 | 非空的有序 { text, voice } 对话轮次列表,最多 10 个不同 voice,总文本不超过 2,000 个 Unicode 字符 |
dialogue[].text | string | 是 | 非空对话内容,音频标签及空白计入字符数 |
dialogue[].voice | string | 是 | voice ID,从下方已验证音色目录复制 |
stability | number | 否 | v3 为 0、0.5 或 1;v4 为 0 到 1 间任意数值;默认 0.5 |
language_code | string | 否 | 如 en、zh、ja、fr,省略或留空时自动检测 |
输出为托管的 MP3 音频文件。此接口不提供实时流式响应或其他输出格式。
已验证音色
目录展示已通过官方账号校验的音色,包括官方默认音色;账号内其他自定义音色不会自动列入目录。名称仅供浏览,提交时请使用 voice ID。音色可能发生可用性变化,替换音色前请刷新目录。
| 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 |
响应
{
"code": 200,
"msg": "success",
"data": {
"taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
Estimate 预估
在不创建任务的情况下预估积分消耗。费用随 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": "你好呀!", "voice": "TX3LPaxmHKxFdv7VOQHJ" }
]
}
}'
查询任务
curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
-H "Authorization: Bearer sk-your-api-key"
状态流转:pending -> processing -> completed 或 failed。
完成
{
"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"
}
}
}
音频 URL 有效期 24 小时。
失败
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "failed",
"model": "elevenlabs-text-to-dialogue-v3",
"created_at": 1775383908,
"error": {
"code": "upstream_error",
"message": "Generation failed"
}
}
任务失败时,预扣的积分会自动退还。
回调
创建任务时传入 callback_url,任务完成或失败时系统会自动向该地址发送 POST 请求,格式与查询任务的响应一致。
常见错误码
请求失败时,API 返回 JSON 格式的错误响应:
{
"error": {
"code": "insufficient_credits",
"message": "Your credit balance is too low. Please top up.",
"type": "billing_error"
}
}
错误码一览
| HTTP 状态码 | 错误码 | 类型 | 说明 |
|---|---|---|---|
| 400 | invalid_request | invalid_request_error | 缺少必填参数或参数无效 |
| 401 | invalid_api_key | authentication_error | API Key 无效、已禁用或已删除 |
| 402 | insufficient_credits | billing_error | 积分余额不足,请充值 |
| 403 | ip_not_allowed | permission_error | 请求 IP 不在 Key 的白名单中 |
| 404 | model_not_found | invalid_request_error | 模型不存在或已停用 |
| 404 | task_not_found | invalid_request_error | 任务 ID 不存在 |
| 429 | rate_limit_exceeded | rate_limit_error | 请求过于频繁,请降低频率 |
| 429 | spend_limit_exceeded | billing_error | 达到 Key 的消费限额(每小时/每天/总量) |
| 500 | internal_error | api_error | 服务器内部错误 |
| 503 | upstream_error | upstream_error | 上游 AI 服务返回错误 |
常见场景
invalid_request (400)
缺少必填字段或参数格式错误时返回。
{
"error": {
"code": "invalid_request",
"message": "'model' is required.",
"type": "invalid_request_error"
}
}
insufficient_credits (402)
积分不足。可通过 GET /v1/credits 查询余额,前往 Dashboard > Billing 充值。
invalid_api_key (401)
可能原因:
- Key 不以
sk-开头 - Key 已被禁用或删除
- 用户账户已被封禁
upstream_error (503)
上游 AI 服务返回错误,可能原因:
- 输入内容包含敏感或违规信息
- 上游服务暂时不可用
- 请求参数不被上游支持
因上游错误导致任务失败时,预扣积分会自动退还。