mcpField
B
byteplus-seed-speech-tts

byteplus-seed-speech-tts

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

关于 byteplus-seed-speech-tts

集成 BytePlus Seed Speech 文本转语音的生产技能，涵盖预置音色及使用已注册且获授权音色进行合成。面向开发者，说明资源与流式协议选择、音频处理，以及质量、授权和运维检查。

主要功能

  1. 01选择 TTS 资源系列与协议
  2. 02通过 WebSocket 或 HTTP 流式传输音频
  3. 03配置语速、格式与上下文控制
  4. 04验证音色和语言支持
  5. 05处理时间戳并检查音频
  6. 06规划授权、计费与错误处理

适用场景

  1. 01根据准备好的文本生成旁白
  2. 02在助手回复生成时流式播放语音
  3. 03批量合成前检查音色、发音和音频输出

安装

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

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

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

附带文件EVAL.md

详细介绍

BytePlus Seed Speech TTS

将此技能用于国际版 BytePlus Seed Speech 服务。目前文档记载的 API 主机位于 ap-southeast-1.bytepluses.com 域名下。请勿将中国大陆版 Volcengine Doubao Speech 的凭据、端点、价格、语音 ID 或商业假设移用于此服务。

验证与证据

  • **文档事实：**官方 BytePlus 文档或适用的法律页面中说明的行为。
  • **生产经验法则：**必须使用所选账户、语音和协议进行测试的实用工作流。
  • **实测观察：**通过实际请求测得的输出，须注明日期。

已于 2026-07-12 核实提供商相关事实。语音清单、语言兼容性、定价、免费额度、并发数、端点、数据保留和协议行为都可能变动。正式上线前，请立即重新核查官方语音列表、API 页面、控制台、定价、订单和 DPA。

范围与分类

BytePlus 将国际版产品称为 Seed Speech。当前的合成资源系列包括：

  • seed-tts-1.0：TTS 1.0；
  • seed-tts-2.0：TTS 2.0；
  • seed-icl-1.0：经授权的 Voice Replication 1.0 合成；
  • seed-icl-2.0：经授权的 Voice Replication 2.0 合成。

Seed-TTS 研究论文介绍的是模型研究内容，并非 API 合约。请勿将研究变体作为托管模型 ID 对外提供。

本部分介绍预置 TTS，以及使用已注册并获授权语音进行合成的情形。语音注册本身需要单独进行同意、数据和生命周期审查。本部分不涵盖 ASR、语音到语音 Agent、口译、播客或中国大陆版 Volcengine API。

选择模型系列和协议

TTS 1.0

当所选语音或所需功能的文档适用于 TTS 1.0 时使用，特别是所选协议文档明确支持时间戳或特定语音的情绪控制时。请勿假设 TTS 1.0 和 TTS 2.0 的语音共用标识符或控制项。

TTS 2.0

BytePlus 文档说明，TTS 2.0 提供更广泛的多语言支持，以及上下文／指令控制。context_texts 可提供自然语言形式的表演指导；文档仅说明列表中的第一个值会生效。section_id 可连接之前的合成上下文，当前文档说明最多支持 30 轮或 10 分钟。

文档所述的 V3 双向或单向路径均不支持 TTS 2.0 的 SSML。切勿将 SSML 作为受支持的控制项发送。

双向 WebSocket

当文本逐步传入，且音频需要在保留会话上下文的同时进行流式传输时使用：

wss://voice.ap-southeast-1.bytepluses.com/api/v3/tts/bidirection

生命周期：建立 WebSocket，执行 StartConnection，等待 ConnectionStarted，执行 StartSession，等待 SessionStarted，发送一个或多个 TaskRequest 事件，接收句子／音频事件，执行 FinishSession，等待 SessionFinished，然后关闭连接。目前的事件代码包括句子开始 350、句子结束 351 和 TTS 响应 352。

单向 HTTP 流式传输

当完整文本已知，且音频应通过 HTTP 流式返回时使用：

POST https://voice.ap-southeast-1.bytepluses.com/api/v3/tts/unidirectional

读取换行分隔／流式 JSON 响应，对每个音频负载进行 base64 解码，并按到达顺序拼接。收到提供商成功代码 20000000 后结束。

验证期间未能确认 BytePlus 提供公开的异步长文本工作流。请勿将国际版任务转发至 Volcengine 异步端点。

身份验证和请求头

新的集成使用通过控制台生成的 X-Api-Key。必须指定所选资源 ID。当前 HTTP 文档还要求使用提供方显示的固定 X-Api-App-Key；请从当前页面核实，不要假定它是机密，也不要重复使用过期值。

请求头格式示例：

X-Api-Key: ${BYTEPLUS_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
X-Api-App-Key: <current documented fixed value>
X-Api-Request-Id: <uuid>
Content-Type: application/json

WebSocket 路径使用 X-Api-Connect-Id 进行故障排查。请保留返回的 X-Tt-Logid 以及客户端请求/连接 ID。切勿记录凭据或敏感源文本。

为保持兼容性，文档仍列出了旧版 App ID/access-key 请求头及旧版资源 ID。不要将新 API 密钥与猜测的旧版字段混用，也不要复制 Volcengine 的身份验证信息。

语音和语言选择

请将支持情况视为一个元组：

voice ID + resource family + protocol + language + control

在执行时加载官方语音列表。请确认账户有权使用该语音，并确认所选语音支持目标语言、协议、情感、时间戳及其他请求的控制项。不要编造 ID，也不要根据 ID 后缀推断功能。

目前，TTS 2.0 概览列出的语言包括英语、中文、日语、德语、法语、墨西哥西班牙语、印度尼西亚语、巴西葡萄牙语、意大利语和韩语。协议/语音页面可能会列出其他特定语音的语言代码。用于生产调用时，应以所选语音页面为准。

请求控制项

当前 V3 请求字段包括文本、说话人、音频格式/采样率、语速、响度、特定语音的情感，以及转义后的 JSON additions 字符串。

文档列出的范围包括：

  • speech_rate：-50 到 100，其中 -50 表示 0.5 倍速，100 表示 2 倍速；
  • loudness_rate：-50 到 100；
  • emotion_scale：支持情感的语音取值为 1 到 5，感知变化并非线性；
  • 格式：mp3、ogg_opus 和 pcm；
  • 采样率：当前协议页面列出的取值范围为 8 kHz 到 48 kHz。

流式 WAV 可能会产生重复的头部；需要无帧流时优先使用 PCM，或者使用 MP3/Opus，并验证拼接/解码是否正确。

additions 控制项包括语言策略、Markdown/表情符号处理、末尾静音、公式规范化、TTS 2.0 上下文以及可选的缓存行为。文档说明，缓存命中时不会返回时间戳。

在估算成本和合成之前，请规范化数字、日期、货币、缩写、URL、公式、Markdown、表情符号和标点。保存请求中使用的确切规范化源文本。

时间戳和字幕

当前 V3 参数表说明，enable_timestamp 仅适用于 TTS 1.0 和 ICL 1.0。缓存响应不包含时间戳。对于在其他模型/协议组合中观察到的任何计时结果，应将其视为账户级实测结果，而非文档所述的功能。

因此：

  • 若没有针对确切语音/协议进行过带日期的集成测试，切勿承诺 TTS 2.0 能提供计时信息；
  • 请验证时间戳单调递增、不超出解码后的时长，并且在文本规范化后仍保持对齐；
  • 请人工审核名称、数字、标点和行分组；
  • 保留备用的转写/对齐工作流；
  • 不要根据估算的字符时长生成字幕。

计费和容量

根据 2026-07-12 核查的官方公开定价，TTS 2.0 提供套餐和按量付费的字符计费方式、20,000 字符的激活试用额度，以及单独购买的并发额度。其定义中，空格、标点、符号和回车均属于计费字符。

价格、套餐和术语可能会变化，请根据当前定价页面/控制台创建带日期的成本记录。请依据提供方当前的计费规则统计规范化后的请求文本。确认账户限制采用并发数还是 QPS 表示，并在批量生产前测试队列行为。

请勿声称某个套餐或试用额度在适用账户和日期范围之外也有保证。

隐私、同意和复制声音

适用的 BytePlus 协议和 DPA 约束数据处理。客户负责告知、合法依据/同意以及授权指示。BytePlus 当前的企业 AI 常见问题对训练相关声明作了限定：除非同时说明企业客户和明确授权的背景，否则不要简化成“数据绝不会用于训练”。

对于任何复制声音：

  • 获得说话者/权利持有者明确且针对特定用途的授权；
  • 记录获准用途、受众、地区、期限、撤销方式和删除流程；
  • 核实账户、语音 ID 和语言均已获授权；
  • 避免冒充公众人物或进行欺骗性冒充；
  • 尽量减少注册/源音频，并限制访问权限；
  • 在当前合同/订单表中明确保留期限、数据驻留、删除和模型改进条款。

成功完成注册或声纹检查不等于取得法律同意。

错误处理

处理提供商/应用程序错误代码，并保留 X-Tt-Logid。

  • 文本、参数无效，控制项不受支持，或语音未获授权：修正问题；不要原样重试。
  • 并发/配额问题：排队、采用带随机抖动的退避策略，或调整已购买的容量。
  • 常规服务器/网络故障：在明确幂等性/计费行为的前提下，进行有限次数的重试。
  • 流式传输部分内容不明确：拒绝不完整音频，除非工作流明确支持续传/重新组装。

不要打印 API 密钥、旧版令牌、敏感文本，或包含客户数据的完整响应正文。

生产环境 QA

在处理完整批次之前，先生成短样本并审批语音、语言、发音、语速、情感和上下文行为。

检查：

  • 解码后的编解码器、采样率、声道数、时长和损坏情况；
  • 缺失/重复/截断的词语以及流顺序；
  • 姓名、首字母缩略词、数字、货币、公式和多语言切换；
  • 削波、真峰值、响度一致性、噪声、咔嗒声、齿音和静音；
  • 表演指导和语音身份；
  • 与规范化文本进行反向转录比对；
  • 如有使用，检查时间戳/字幕对齐情况；
  • 请求/资源/语音/日志 ID、源版本、同意记录、价格证据和输出哈希。

提供商的输出可能因调用而异。除非经过测量且有合同支持，否则不要承诺同一请求会生成逐位相同的语音。

示例 1：TTS 2.0 HTTP 旁白

这是一个完整示例，并非强制公式。

**意图：**以低延迟、平和的表演指导生成中文产品旁白。

预先检查当前语音列表，并选择一个获准使用的 TTS 2.0 中文语音。使用 seed-tts-2.0、24 kHz MP3、准确的规范化脚本，以及一条 context_texts 指令：“自然、平和、温暖地朗读；避免夸张。”向单向 HTTP 端点提交请求，按顺序接收每个音频块，并在收到 20000000 时停止。

载荷结构如下：

{
  "user": {"id": "production-job-2841"},
  "req_params": {
    "text": "欢迎回来。项目已经准备就绪，我们现在可以开始。",
    "speaker": "<authorized-current-voice-id>",
    "audio_params": {
      "format": "mp3",
      "sample_rate": 24000,
      "speech_rate": 0,
      "loudness_rate": 0
    },
    "additions": "{\"explicit_language\":\"zh-cn\",\"disable_markdown_filter\":true,\"context_texts\":[\"请用自然、沉稳、亲切的语气表达，不要夸张。\"]}"
  }
}

对解码后的音频、时长、脚本完整性、发音、表演效果和日志 ID 进行 QA。除非该语音/协议已通过有日期记录的测试，否则不要请求时间戳。

示例 2：渐进式助手响应

这是一个完整示例，并非强制公式。

**意图：**响应文本逐步到达时，流式生成获准使用的英语助手语音。

采用双向 WebSocket 生命周期。使用获准的语音/资源组合启动连接/会话，将完整的语义片段作为 TaskRequest 事件发送，接收句子/音频事件，并且仅在最后一个片段完成后结束。整个会话期间保持一致的表演指令和上下文策略。缓存足够的文本，以避免产生不自然的片段，同时不要过度延迟首段有用音频。

对片段边界、缺失/重复文本、顺序、取消、重新连接、速率限制，以及最终转录与音频的一致性进行 QA。如果所选语音不支持双向操作，则在获得明确批准后切换协议或语音；不要悄悄替换。

来源

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

评论

支持 Markdown