doubao-tts

用途

Doubao TTS 用于生成普通话和多语种旁白，基于火山引擎豆包语音 2.0。适合制作中文配音、视频旁白等需要语音合成的场景。

主要能力

支持普通话及多语种语音合成。
提供同步与异步两种调用方式；长视频旁白建议使用异步接口：
- POST https://openspeech.bytedance.com/api/v3/tts/submit
- POST https://openspeech.bytedance.com/api/v3/tts/query
异步接口返回 audio_url 以及 sentences[].words[] 时间戳元数据，可用于构建字幕。
可通过参数控制音色、语速、采样率，并可启用时间戳和用量元数据返回。

使用方式

先在 .env 中配置 DOUBAO_SPEECH_API_KEY，并可用 DOUBAO_SPEECH_VOICE_TYPE 设置默认音色，或在调用时传入 voice_id。

新控制台 API Key 认证方式：

X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0

不要将 X-Api-App-Id 和 X-Api-Access-Key 与新控制台 API Key 混用。

通过 TTS 选择器生成：

from tools.audio.tts_selector import TTSSelector

result = TTSSelector().execute({ "preferred_provider": "doubao", "text": "如果 AI 真的会改变未来，普通人到底该怎么参与？", "voice_id": "zh_female_vv_uranus_bigtts", "output_path": "projects/my-video/assets/audio/narration.mp3", "speech_rate": 0, "enable_timestamp": True, })

或直接调用提供者：

from tools.audio.doubao_tts import DoubaoTTS

result = DoubaoTTS().execute({ "text": "短样本试听文本。", "voice_id": "zh_female_vv_uranus_bigtts", "output_path": "projects/my-video/assets/audio/doubao_sample.mp3", })

提供者会写出 output_path（下载的音频文件）和 metadata_path（完整查询响应 JSON，默认为 <output_path>.json）。

参数

voice_id：豆包音色/voice type，默认取 DOUBAO_SPEECH_VOICE_TYPE。
resource_id：豆包语音 2.0 音色使用 seed-tts-2.0。
speech_rate：0 为正常，100 为 2 倍，-50 为 0.5 倍。
sample_rate：默认 24000。
enable_timestamp：默认 true。
return_usage：默认 true，在可用时请求用量元数据。

默认不要传 additions.explicit_language，部分端点与密钥组合会因不支持 zh-cn 而报错。

限制与排错

load grant: requested grant not found：密钥类型或认证头错误，新控制台 API Key 应使用 X-Api-Key。
speaker permission denied：voice id 错误或未对所选资源授权。
quota exceeded：配额、字符额度或并发超限。
缺少时间戳：确认 enable_timestamp 为 true，保留查询 JSON，并确认所选端点返回了 sentences。

安全要求：不得将 API Key 打印或写入日志、元数据、补丁或项目产物；.env.example 只应包含空变量名。

技能介绍

用途

主要能力

使用方式

参数

推荐工作流

限制与排错