mcpField
V
volcengine-doubao-speech-tts

volcengine-doubao-speech-tts

github.com/calesthio创意与媒体219100 次安装15 周前更新
代码仓库

关于 volcengine-doubao-speech-tts

用于中国大陆 Volcengine Doubao Speech API 的工作流技能，涵盖文本转语音、流式音频和长文本任务。它帮助团队选择兼容的音色与协议、管理异步结果，并处理授权和生产质量检查。

主要功能

  1. 01说明流式与异步 TTS
  2. 02涵盖音色和协议兼容性
  3. 03指导长文本任务处理
  4. 04说明克隆音色授权要求
  5. 05列出生产音频质检项

适用场景

  1. 01为助手生成流式语音
  2. 02生成有声书章节
  3. 03选择兼容的音色和协议
  4. 04审查克隆音色授权

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill volcengine-doubao-speech-tts

安装后在 Claude Code 中输入/volcengine-doubao-speech-tts确认已加载。

附带文件EVAL.md

详细介绍

Volcengine Doubao Speech TTS

将此技能用于中国大陆的 Volcengine Doubao Speech。请勿将 BytePlus API 主机、密钥、定价、法律条款或相关假设带入此工作流。两项服务使用相同的模型系列术语，但属于不同的区域产品。

验证与证据

  • 文档事实： 官方 Volcengine 页面中说明的行为。
  • 生产启发： 需要在目标账户中测试的工作流建议。
  • 实证观察： 在实际账户/区域中，基于带日期请求得到的结果。

事实已于 2026-07-12 验证。语音列表、协议兼容性、定价、激活、配额、数据保留、区域可用性和法律条款可能变化。请重新查阅中文官方文档和经过身份验证的控制台。

产品与 API 边界

当前合成资源系列包括：

  • seed-tts-1.0：V3 上的 TTS 1.0；
  • seed-tts-2.0：V3 上的 TTS 2.0；
  • seed-icl-1.0：经授权的克隆语音 1.0 合成；
  • seed-icl-2.0：经授权的克隆语音 2.0 合成。

旧版 volc.service_type.10029 和 V1 API 属于较早的 TTS 1.0 合约。请勿通过 V1 调用 TTS 2.0 语音，也不要用旧版模型选择器替代 V3 资源 ID。

本文仅介绍合成和长文本生产。语音注册仅作为同意/授权边界说明；ASR、语音 Agent、口译、播客、语音到语音以及国际版 BytePlus 均不在讨论范围内。

选择协议

V3 双向 WebSocket

适用于文本逐步到达的情况：

wss://openspeech.bytedance.com/api/v3/tts/bidirection

遵循文档说明的连接/会话/任务生命周期。并非所有语音都支持所有协议；在确定采用双向传输前，请核实当前语音列表和账户权限。

V3 单向流式传输

适用于文本内容已完整确定、但音频需要流式传输的情况。Volcengine 官方文档包含 V3 WebSocket、HTTP 分块传输和 SSE 接口。实现时，请选择文档明确说明的具体端点和响应解析器；不要假定不同传输方式的架构可以互换。

异步长文本

适用于批量旁白/有声读物，以及符合当前文档所述限制的输入：

POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query

当前文档规定的上限为 100,000 个字符。提交后会返回 task_id；查询状态为 1（运行中）、2（成功）和 3（失败）。成功后请立即下载。文档说明服务器上的音频保留七天；每个返回 URL 的有效期为一小时，可再次查询以刷新。

提交和查询都会占用已购并发池。请采用带抖动的有限轮询，并持久化服务提供方的任务 ID。

身份验证

Volcengine V3 流式和异步页面规定了不同的请求头组合。请遵循所选页面中的具体说明。

当前 V3 新控制台集成在相关流式接口上使用 X-Api-Key。异步长文本 API 文档规定：

X-Api-App-Id: ${VOLC_APP_ID}
X-Api-Access-Key: ${VOLC_ACCESS_KEY}
X-Api-Resource-Id: seed-tts-2.0
X-Api-Request-Id: <uuid>

旧版 V1 使用特殊的 Authorization: Bearer;${token} 格式。若无最新文档支持，请勿将其复制到 V3。

请保留返回的请求 ID 和 X-Tt-Logid。切勿记录密钥、令牌、注册音频或敏感源文本。

语音、语言与控制兼容性

请将支持情况视为：

speaker + resource ID + protocol + language + control + account entitlement

加载当前官方语音列表。不要固定语音数量、根据后缀推断支持情况，也不要编造 ID。部分多语言/当前语音可能仅支持单向操作。

文档列出的控制项包括：特定语音的情绪、非线性的 emotion_scale（1 到 5）、speech_rate（-50 到 100）、loudness_rate（-50 到 100）、采样率/格式、结束静音、语言过滤、Markdown/表情符号/公式处理，以及可选的 AIGC 水印设置。

TTS 2.0 使用上下文/指令控制，并且在文档说明的 V3 路径上不支持 SSML。SSML 支持仅适用于兼容的 TTS 1.0 路径；使用前请核实具体标签和限制。

混用语音或跨版本沿用控制项并非通用做法。当前语音/协议页面是权威依据。

时间戳和文本规范化

时间戳文档因版本和协议而异。Volcengine 异步结果可以返回句子/词语时间结构，但必须针对确切的音色测试 TTS 2.0/ICL 2.0 的支持情况和规范化行为。

  • 提交和计费前规范化文本。
  • 记录规范化前后的文本形式。
  • 验证时间戳单调性、时长范围、数字、标点和改写后的文本。
  • 中文字幕应按语义短语分组，而不是按固定字数分组。
  • 时间信息缺失或不准确时，保留对齐备用方案。
  • 不要将缓存/估算的字符时间用作字幕依据。

异步幂等性和结果保管

设置稳定的调用方 unique_id，并将其与 task_id、源哈希、规范化文本、资源/说话人和尝试次数一并保存。

发生不明确的超时后，先查询已知任务状态，再重新提交。盲目重新提交可能导致重复工作或重复收费。成功后，在 URL 过期前下载文件，计算校验和，验证解码和时长，并将资源移至受控存储中。结果 URL 不是持久的交付位置。

定价、激活和配额

在验证期间可获取的未认证文档中，无法确认公开的人民币价格；已认证控制台和订单条款具有权威性。文档说明，异步长文本使用相应的短文本 TTS/语音复刻定价，而非单独的高级定价。

付费使用前，请记录：

  • 账号/区域和已激活的资源；
  • 字符数或并发套餐；
  • 当前单价和有效期；
  • 实际获赠的免费/试用额度；
  • 特定音色的费用/权益；
  • 预期规范化字符数和尝试次数；
  • 已购买的并发数和队列策略。

没有当前账号证据时，不要承诺公开的免费套餐、区域范围或固定费率。

隐私、同意和克隆音色

声音及其关联身份可能属于敏感个人数据。公开产品文档不能替代适用的合同、隐私条款和法律审查。

对于克隆音色：

  • 要求获得明确、可记录且针对特定用途的授权；
  • 记录源说话人、允许的用途、期限、地域范围、分发、撤销和删除事项；
  • 限制注册音频和模型标识符的访问；
  • 通过账号/合同/支持渠道确认当前训练音频/模型的保留和删除情况；
  • 避免欺骗性冒充、公众人物、未成年人以及未经授权的跨语言使用；
  • 记录披露/水印要求。

技术注册或相似度检查均不能证明已获得法律授权。不要声称未经核实的数据驻留、保留、排除训练或法规合规情况。

错误和重试

当前 API 使用成功代码 20000000；请保留详细的提供方代码/消息/日志 ID。

  • 参数/文本/资源/说话人无效或协议不受支持：修正问题；不要原样重试。
  • 说话人权限/资源不匹配：确认激活状态及版本是否匹配。
  • 配额/并发限制：排队/退避，或购买容量。
  • 请求/ID 重复：查询现有任务，或生成适当的新 ID。
  • 一般后端/网络错误：在幂等性保护下进行有限次数的重试。
  • 异步状态 3：显示失败详情；不要隐瞒或无限轮询。

生产环境 QA

为姓名、品牌、首字母缩略词、数字、日期、货币、公式、方言和领域术语创建发音测试集。长任务开始前，先生成审批样本。

验证：

  • 编解码器、采样率、声道、时长、校验和及文件完整性；
  • 文本缺失/重复/截断；
  • 音色身份、语言/方言、语速、情绪和发音；
  • 削波、峰值、响度一致性、噪声、静音、爆音和齿音；
  • 与规范化源文本进行回转转写；
  • 时间戳/字幕对齐；
  • 任务/请求/资源/说话人/日志 ID、价格证据、同意记录、源版本和输出来源。

示例 1：异步有声书章节

这是一个完整示例，并非强制模板。

**意图：**使用获授权的 TTS 2.0 音色合成中国大陆地区的有声书章节。

预先检查当前音色的兼容性，规范章节文本并计算其哈希值，计算当前计费字符数，并取得价格和并发限制方面的批准。使用异步必需的请求头、稳定的 unique_id、namespace: "BidirectionalTTS"、seed-tts-2.0、MP3 24 kHz，以及准确的当前获授权说话人 ID 提交任务。

{
  "user": {"uid": "audiobook-pipeline"},
  "unique_id": "chapter-0047-v3-9b2f8c4a",
  "namespace": "BidirectionalTTS",
  "req_params": {
    "text": "<normalized-chapter-text>",
    "speaker": "<authorized-current-voice-id>",
    "audio_params": {
      "format": "mp3",
      "sample_rate": 24000,
      "speech_rate": 0,
      "loudness_rate": 0,
      "enable_timestamp": true
    },
    "additions": "{\"disable_markdown_filter\":true,\"explicit_language\":\"zh-cn\"}"
  }
}

通过 task_id 轮询；状态为 2 时立即下载，并保存时间信息载荷、校验和、解码后的时长及 URL 过期时间。由人工审核章节和字幕。如果此特定 TTS 2.0 音色未返回可用的时间信息，请单独进行对齐。

示例 2：双向助手

这是一个完整示例，并非强制模板。

**意图：**随着文本到达，流式生成普通话助手语音。

明确选择当前文档说明支持双向 V3 的音色及其匹配的资源。使用 PCM 或经过测试的流式编码格式、稳定的连接和会话 ID，以及有界的语义文本缓冲策略。遵循 StartConnection/StartSession/TaskRequest/FinishSession 事件；当上游文本被放弃时，妥善取消。

首先对首段音频行为、分块顺序、句子边界、重新连接/取消、缺失/重复文本、使用权限、并发限制以及最终转录一致性进行质量检查。如果所需音色仅支持单向模式，请征得用户批准后再更改音色或协议。

来源

已核实的官方来源（2026-07-12）：

评论

支持 Markdown