豆包 TTS
需要在 .env 文件中设置 DOUBAO_SPEECH_API_KEY。
设置 DOUBAO_SPEECH_VOICE_TYPE 以指定默认音色,或在调用工具时传入 voice_id。
当前 API
使用新版控制台的 API Key 流程:
X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
如果使用的是新版控制台的 API Key,请不要使用 X-Api-App-Id 和 X-Api-Access-Key。如果 API 返回 load grant: requested grant not found,则说明密钥类型或认证头部可能有误。
对于长视频旁白,建议使用异步端点:
POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query
这将返回 audio_url 以及可用于构建字幕的 sentences[].words[] 时间信息。
OpenMontage 使用方法
通过 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
推荐工作流程
- 在付费生成完整旁白前,先生成一个 10-15 秒的样本。
- 请用户确认声音的自然度、口音和语速是否合适。
- 仅在用户批准后,再生成完整的旁白。
- 保留查询 JSON。它是字幕时间信息的权威来源。
- 根据
sentences[].words[]构建字幕,而不是根据估算的文本长度。 - 在应用时间戳之前,按中文语义短语对字幕进行分组。不要仅按固定字符数拆分,这可能会破坏类似“在不押单个公司的情况下”或“可能会被慢慢稀释”等短语,从而影响理解。
- 让视频时长遵循已批准的语音节奏,除非用户明确要求匹配之前的运行时。
参数
voice_id: 豆包speaker/ 音色类型。默认为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 并返回 unsupported additions explicit language zh-cn。
对于平静的普通话解说视频,从 speech_rate: 0 开始。如果结果对于已批准的格式来说过长,在重新生成完整旁白前,先制作一个语速为 25 或 50 的简短对比样本。如果用户更喜欢豆包自然的节奏,请不要仅仅为了匹配之前提供者的时长而加快语速。
故障排除
load grant: requested grant not found: 密钥类型错误或认证头部错误。对新版控制台 API Key 使用X-Api-Key。speaker permission denied: 音色 ID 错误或未获所选资源的授权。quota exceeded: 超过了配额、生命周期字符数或并发限制。Missing timestamps: 确认enable_timestamp: true,保留查询 JSON,并确认所选端点返回了sentences。
安全
切勿将 API 密钥打印或写入日志、元数据、补丁或项目工件中。.env.example 应仅包含空的变量名。