使用指南
ElevenLabs Text to Dialogue 使用指南:用 dialogue 数组提交双人对话音频
从双人脚本拆分到逐句音色请求,按 HiAPI 当前契约提交与验收
本页内容
先确认你要解决的是对话合成而非单段朗读
如果你的素材是一段双人(或多角色)对话脚本,最直接的做法往往是把每句台词单独合成、再按顺序拼起来。这种方式的问题在交付阶段才显现:每句都是一个独立音频,句间的停顿、语速衔接、音色一致性都要你在拼接层再补一遍;角色一多,拼接顺序和音色错配就成了主要 bug 来源。
elevenlabs/text-to-dialogue 的定位是一次请求表达整段对话。你把整段脚本拆成 dialogue 数组提交,由模型在同一次生成里完成多音色对话,输出是一条完整音频。相比「多次单段合成 + 拼接」,它把角色映射和行序都收进了请求体,验收时你只需要检查一条结果。
因此先做一个判断:
- 内容是同一说话人的连续朗读,用文本转语音即可,不需要
dialogue数组; - 内容是两个及以上角色交替的对话,且你希望整体听感统一,应使用本接口的
dialogue数组; - 内容是对话但总字符远超上限,则需要按语义切段、分段提交,而不是退回逐句合成。
确定属于第二类后,接下来要弄清的是数组本身的结构。

dialogue 数组的结构:每行 text 与 voice
在 HiAPI 的契约里,elevenlabs/text-to-dialogue 的输入核心只有一个必填字段:dialogue。它是一个数组,最少 1 项,每个元素是一行对话,包含两个必填子字段:
text:该行台词的文本,字符串,最少 1 个字符;voice:该行使用的音色,字符串,可填预设音色名或voice_id,默认EkK5I93UQWFDigLMpZcX。
两个字段都是必填的——即使你只想用默认音色,也建议显式写出 voice,让请求体自解释。一个最小的双人请求形态如下:
{
"dialogue": [
{ "text": "你那边进度怎么样?", "voice": "EkK5I93UQWFDigLMpZcX" },
{ "text": "本周能出第一版。", "voice": "Z3R5wn05IrDiVCyEkUrK" },
{ "text": "好,那我先把验收清单发你。", "voice": "EkK5I93UQWFDigLMpZcX" }
]
}
注意数组的顺序即对话顺序,接口没有额外的「说话人」字段,角色完全靠 voice 区分。这是整个接入过程中最需要提前设计的一点。

把双人脚本拆成逐句条目
从剧本文本到 dialogue 数组,建议按固定流水线处理,避免手写 JSON 出错。
第一步:按行切分并标注说话人
把脚本整理成「说话人 + 台词」的成对结构,一句一条,不要把两个角色的台词合并进同一个 text——那样一个元素只能挂一个 voice,合并后无法区分角色。旁白、括号里的舞台说明不属于台词,应单独剔除,不要塞进 text。
第二步:清洗文本
逐条检查:去掉首尾空白、统一标点和换行、删除空行。text 的最短长度约束是 1 个字符,空字符串会直接触发校验失败。如果某行只有语气词(如「嗯」「对」),保留即可;但如果清洗后变成空串,就要和内容方确认是否删掉该行。
第三步:建立角色映射并生成数组
每个说话人标签映射到唯一音色,再按行序生成元素。伪代码大致是:
speaker_voice = {
"A": "EkK5I93UQWFDigLMpZcX",
"B": "Z3R5wn05IrDiVCyEkUrK",
}
dialogue = [
{"text": line.text, "voice": speaker_voice[line.speaker]}
for line in script
]
常见坑
- 同一角色在两处用了不同音色,听感会明显割裂;
- 漏写
voice导致整段回落默认音色,双人对话变成「一人分饰两角」; - 数组顺序被排序或去重逻辑打乱,对话语义断裂。
生成后先打印前几条元素人工核对,再进入字符预算这一关。
固定音色映射:同一角色只用一个 voice
voice 之所以要「固定」,是因为它既决定音色本身,也承担了「这是谁在说话」的语义。同一角色在整段对话里若出现两个不同的 voice 值,听众会认为换人了;反过来,两个角色如果撞到同一个 voice,对话就失去区分度。
实践上建议在代码里维护一张角色到音色的常量映射表,而不是在每行台词里散落字符串字面量:
const VOICE = {
host: "EkK5I93UQWFDigLMpZcX",
guest: "Z3R5wn05IrDiVCyEkUrK",
};
所有行只从这张表取值,脚本换行、重排都不会破坏一致性。voice 支持预设音色名或 voice_id;如果团队已有自己的音色命名体系,可以在配置层做一次转换,落到请求时统一成接口认可的值。契约中给出了音色枚举,提交前用枚举校验一次,能挡住拼写错误这类低级问题——枚举外的值不会被悄悄当成默认值处理。
另一个常被忽略的点是跨段落的稳定性。当总字符超过上限、需要拆成多次请求时,音色映射表要原样复用,不要在新请求里重新挑音色,否则同一角色在不同段落会听出差异。

字符预算与请求拆分
接口对体量有一条硬约束:dialogue 数组中所有 text 字段的字符总数不得超过 5000。注意是数组内所有文本之和,不是单行长度,也不是元素个数。中文、英文、标点通常都按字符计入,估算时宁可按最宽口径留出余量。
计数逻辑应写在生成数组之后、发请求之前:
total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000
超过上限时,正确的做法是按语义边界切分成多个子对话,分别提交、分别拿到音频,再按业务需要组合;而不是截断台词或删句。切分时注意三点:
- 切点选在场景切换、话题转换处,避免把一问一答拆到两次请求里;
- 每个子片段单独计数,同样不超过 5000;
- 切分后的每个片段重建数组时保持原有行序与角色音色映射。
如果内容本身就是长对话,建议在内容侧就按「幕」或「章节」组织,使每幕天然落在预算内,减少临时切分带来的听感断层。
可选参数:stability 与 language_code
除了 dialogue,接口还提供两个可选参数,取舍取决于内容类型。
stability
stability 是数值参数,可取 0、0.5、1,默认 0.5。语义是音色稳定性:
- 取值越小,情感越丰富、变化越多,适合有情绪起伏的对话、剧情类内容;
- 取值越大,输出越稳定一致,适合品牌播报、客服话术这类要求统一听感的场景;
- 默认 0.5 是两者之间的折中。
注意这是整次请求级别的参数,不是逐行设置。同一段对话里角色情绪差异很大时,要么接受一个折中值,要么在切分段落时让不同片段使用不同的 stability。
language_code
language_code 是 ISO 格式语言代码,默认空字符串,留空表示自动检测语言。当内容语言明确、且希望避免检测偏差时,显式指定更稳妥,例如中文内容填 zh。契约中给出了完整的语言代码枚举,提交前应做一次校验,避免传入不被支持的值。
两个参数都不是必填项;如果内容没有特殊要求,省略它们、使用默认行为是完全可以的。
提交与验收:按任务式契约检查
该接口以任务形式提交:你发送输入,拿到一个任务结果,再围绕这个结果做验收。这意味着两件事。
第一,输入契约要自己校验。在发请求前逐项检查:dialogue 是数组且至少 1 项;每项同时有非空的 text 和 voice;所有 text 字符总数不超过 5000;stability 只取 0/0.5/1;language_code 属于枚举或留空。把这些检查放在客户端,能显著减少无效提交。
第二,不要假设契约未声明的行为。接口文档没有承诺自动重试、幂等键或失败补偿,因此不要靠「重复提交同一次请求」来兜底——每次提交都应被视为一次独立任务。工程上的稳妥做法是:
- 提交前记录本次请求的输入摘要(数组条数、字符总数、音色映射版本),便于事后比对;
- 拿到结果后先确认音频可用、时长合理、角色可区分,再做下游分发;
- 若需要重跑,重新走一遍完整的输入校验,而不是复用未经验证的旧请求体。
验收的重点是「结果是否符合预期」,而不是推测服务端的内部流程。在 HiAPI 上,你可以从 elevenlabs/text-to-dialogue 模型页 查看当前契约再动手。
上线前的自检清单
把下面这组检查固定成提交前的自动流程,基本可以覆盖绝大多数失败原因:
dialogue是数组,元素数 ≥ 1;- 每个元素都同时包含
text与voice,且都不是空串; - 每个
voice都在契约枚举内,且同一角色全局只用同一个值; - 数组顺序与脚本行序一致,没有排序或去重逻辑介入;
- 所有
text字符总数 ≤ 5000,超限内容已按语义切分; - 如显式设置,
stability∈ {0, 0.5, 1},language_code∈ 枚举或为空; - 输入摘要(条数、字符数、映射版本)已记录,便于验收比对。
清单之外,还有一条经验规则:先在短样本上跑通端到端,再放大到整段脚本。角色映射和字符预算这两类问题,在几十行的样本上就能暴露,没必要等到整篇内容提交后才发现。