豆包 TTS(Doubao TTS)
需要在 .env 中設定 DOUBAO_SPEECH_API_KEY。
設定 DOUBAO_SPEECH_VOICE_TYPE 以指定預設語者,或透過工具參數傳入 voice_id。
目前 API
使用新控制台 API 金鑰流程:
X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
使用新控制台 API 金鑰時,請勿使用 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。某些端點/金鑰組合會以 unsupported additions explicit language zh-cn 拒絕 zh-cn。
對於平穩的普通話解說影片,建議從 speech_rate: 0 開始。如果結果對審核格式而言過長,在重新生成完整配音前,先製作一個 speech_rate: 25 或 50 的短比較樣本。如果使用者偏好豆包的自然節奏,請不要只為了匹配先前提供者的時長而加快語速。
排解問題
load grant: requested grant not found:金鑰類型錯誤或認證標頭錯誤。使用新控制台 API 金鑰時請使用X-Api-Key。speaker permission denied:語者 ID 錯誤或未授權用於所選資源。quota exceeded:配額、終身字元數或並發數已超限。- 缺少時間戳記:請確認
enable_timestamp: true,保留查詢 JSON,並確認所選端點有回傳sentences。
安全
絕不將 API 金鑰列印或寫入日誌、元資料、修補檔或專案成品中。.env.example 應僅包含空的變數名稱。