博客

使用指南

ElevenLabs Text to Dialogue 使用指南:用 dialogue 数组提交双人对话音频

从双人脚本拆分到逐句音色请求,按 HiAPI 当前契约提交与验收

2026年11月18日 6 分钟阅读
深绿底色上的扁平织纹格栅封面,黄铜色与暗绿丝带交错成开放网状,呼应双人对话主题。
本页内容

先确认你要解决的是对话合成而非单段朗读

如果你的素材是一段双人(或多角色)对话脚本,最直接的做法往往是把每句台词单独合成、再按顺序拼起来。这种方式的问题在交付阶段才显现:每句都是一个独立音频,句间的停顿、语速衔接、音色一致性都要你在拼接层再补一遍;角色一多,拼接顺序和音色错配就成了主要 bug 来源。

elevenlabs/text-to-dialogue 的定位是一次请求表达整段对话。你把整段脚本拆成 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 数组的树状结构:数组为根,每个元素分出必须同时存在的 text 与 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

超过上限时,正确的做法是按语义边界切分成多个子对话,分别提交、分别拿到音频,再按业务需要组合;而不是截断台词或删句。切分时注意三点:

  1. 切点选在场景切换、话题转换处,避免把一问一答拆到两次请求里;
  2. 每个子片段单独计数,同样不超过 5000;
  3. 切分后的每个片段重建数组时保持原有行序与角色音色映射。

如果内容本身就是长对话,建议在内容侧就按「幕」或「章节」组织,使每幕天然落在预算内,减少临时切分带来的听感断层。

可选参数: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 模型页 查看当前契约再动手。

上线前的自检清单

把下面这组检查固定成提交前的自动流程,基本可以覆盖绝大多数失败原因:

  1. dialogue 是数组,元素数 ≥ 1;
  2. 每个元素都同时包含 text 与 voice,且都不是空串;
  3. 每个 voice 都在契约枚举内,且同一角色全局只用同一个值;
  4. 数组顺序与脚本行序一致,没有排序或去重逻辑介入;
  5. 所有 text 字符总数 ≤ 5000,超限内容已按语义切分;
  6. 如显式设置,stability ∈ {0, 0.5, 1},language_code ∈ 枚举或为空;
  7. 输入摘要(条数、字符数、映射版本)已记录,便于验收比对。

清单之外,还有一条经验规则:先在短样本上跑通端到端,再放大到整段脚本。角色映射和字符预算这两类问题,在几十行的样本上就能暴露,没必要等到整篇内容提交后才发现。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档