豆包 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,可能是 Key 類型或認證標頭錯誤。
對於長篇影片旁白,建議使用非同步端點:
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 開始。如果結果對於已批准的格式來說太長,請先製作一個短比較樣本(使用 speech_rate: 25 或 50),再重新生成完整配音。如果使用者偏好豆包的自然節奏,不要為了匹配先前供應商的時長而加速。
疑難排解
load grant: requested grant not found:Key 類型錯誤或認證標頭錯誤。對新控制台 API Key 使用X-Api-Key。speaker permission denied:語音 ID 錯誤或未獲授權使用所選資源。quota exceeded:超過配額、生命週期字元數或並發數。- 缺少時間戳:確認
enable_timestamp: true,保留查詢 JSON,並確認所選端點回傳了sentences。
安全性
切勿將 API Key 列印或寫入日誌、元數據、修補程式或專案成品中。.env.example 應僅包含空的變數名稱。