ElevenLabs Text-to-Dialogue v3 / v4

使用 ElevenLabs Eleven v3 或 v4 生成自然、富有表现力的多角色对话音频。传入一组对话轮次,每轮指定各自的声音(voice),即可得到一段托管的音频文件。支持多语言。

模型

模型名称稳定性输出
elevenlabs-text-to-dialogue-v30、0.5 或 1,默认 0.5MP3
elevenlabs-text-to-dialogue-v40 到 1 之间任意数值,默认 0.5MP3

可在 Playground 体验 v3 或 v4。两个模型使用相同的请求与任务响应格式。

生成请求直接调用 官方 Text-to-Dialogue API。新版模型能力参见 Eleven v4 官方介绍。

计费

两个模型均为 每 1,000 个 Unicode 字符 24 积分,无最低消费。统计所有 dialogue[].text 的字符数,包括空格、换行和音频标签,按一次请求的总价四舍五入到两位小数。Emoji 等补充平面 Unicode 字符按一个字符计算。

字符数基础积分
10.02
1002.40
1,00024.00
2,00048.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"
    }
  }'

请求体

字段类型必填说明
modelstring是elevenlabs-text-to-dialogue-v3 或 elevenlabs-text-to-dialogue-v4
inputobject是生成参数,见下
callback_urlstring否任务完成/失败时接收通知的回调地址

Input 对象

字段类型必填说明
dialoguearray是非空的有序 { text, voice } 对话轮次列表,最多 10 个不同 voice,总文本不超过 2,000 个 Unicode 字符
dialogue[].textstring是非空对话内容,音频标签及空白计入字符数
dialogue[].voicestring是voice ID,从下方已验证音色目录复制
stabilitynumber否v3 为 0、0.5 或 1;v4 为 0 到 1 间任意数值;默认 0.5
language_codestring否如 en、zh、ja、fr,省略或留空时自动检测

输出为托管的 MP3 音频文件。此接口不提供实时流式响应或其他输出格式。

已验证音色

目录展示已通过官方账号校验的音色,包括官方默认音色;账号内其他自定义音色不会自动列入目录。名称仅供浏览,提交时请使用 voice ID。音色可能发生可用性变化,替换音色前请刷新目录。

NameStylevoice_idPreview
Liam - Energetic, Social Media CreatorA young adult with energy and warmth - suitable for reels and shorts.TX3LPaxmHKxFdv7VOQHJ
Callum - Husky TricksterDeceptively gravelly, yet unsettling edge.N2lVS1w4EtoT3dr4eOWO
Laura - Enthusiast, Quirky AttitudeThis young adult female voice delivers sunny enthusiasm with a quirky attitude.FGY2WhTYpPnrIDTdsKH5
Bella - Professional, Bright, WarmThis 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 ComfortingMiddle-aged man with a resonant and comforting tone. Great for narrations and advertisements.nPczCjzI2devNBz1zQrb
Roger - Laid-Back, Casual, ResonantEasy going and perfect for casual conversations.CwhRBWXzGAHq8TQ4Fs17
Sarah - Mature, Reassuring, ConfidentYoung adult woman with a confident and warm, mature quality and a reassuring, professional tone.EXAVITQu4vr4xnSDxMaL
Charlie - Deep, Confident, EnergeticA young Australian male with a confident and energetic voice.IKne3meq5aSn9XLyUdCD
George - Warm, Captivating StorytellerWarm resonance that instantly captivates listeners.JBFqnCBsd6RMkjVDRZzb
River - Relaxed, Neutral, InformativeA relaxed, neutral voice ready for narrations or conversational projects.SAz9YHcvj6GT2YYXdXww
Harry - Fierce WarriorAn animated warrior ready to charge forward.SOYHLrjzK2X1ezoPC6cr
Alice - Clear, Engaging EducatorClear and engaging, friendly woman with a British accent suitable for e-learning.Xb7hH8MSUJpSbSDYk0k2
Matilda - Knowledgable, ProfessionalA professional woman with a pleasing alto pitch. Suitable for many use cases.XrExE9yKIg1WjnnlVkGX
Will - Relaxed OptimistConversational and laid back.bIHbv24MWmeRgasZH58o
Jessica - Playful, Bright, WarmYoung and popular, this playful American female voice is perfect for trendy content.cgSgspJ2msm6clMCkdW9
Eric - Smooth, TrustworthyA smooth tenor pitch from a man in his 40s - perfect for agentic use cases.cjVigY5qzO86Huf0OWal
Chris - Charming, Down-to-EarthNatural and real, this down-to-earth voice is great across many use-cases.iP95p4xoKVk53GoZ742B
Daniel - Steady BroadcasterA strong voice perfect for delivering a professional broadcast or news story.onwK4e9ZLuTAKqWW03F9
Lily - Velvety ActressVelvety British female voice delivers news and narrations with warmth and clarity.pFZP5JQG7iQjIQuC4Bku
Adam - Dominant, FirmA 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, BalancedFriendly 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 状态码错误码类型说明
400invalid_requestinvalid_request_error缺少必填参数或参数无效
401invalid_api_keyauthentication_errorAPI Key 无效、已禁用或已删除
402insufficient_creditsbilling_error积分余额不足,请充值
403ip_not_allowedpermission_error请求 IP 不在 Key 的白名单中
404model_not_foundinvalid_request_error模型不存在或已停用
404task_not_foundinvalid_request_error任务 ID 不存在
429rate_limit_exceededrate_limit_error请求过于频繁,请降低频率
429spend_limit_exceededbilling_error达到 Key 的消费限额(每小时/每天/总量)
500internal_errorapi_error服务器内部错误
503upstream_errorupstream_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 服务返回错误,可能原因:

  • 输入内容包含敏感或违规信息
  • 上游服务暂时不可用
  • 请求参数不被上游支持

因上游错误导致任务失败时,预扣积分会自动退还。