豆包語音 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 使用方式
使用語音合成選擇器生成:
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。某些端點/金鑰組合會因「不支援的 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 應僅包含空的變數名稱。