豆包 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。某些端點/金鑰組合會拒絕 zh-cn 並回傳 unsupported additions explicit language 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 應僅包含空的變數名稱。