fish.audio TTS
需要在 .env 中設定 FISH_AUDIO_API_KEY(可在 https://fish.audio/go-api/api-keys/ 建立)。
在 fish.audio 遊樂場建立語音模型,並將其 ID 作為 reference_id 傳遞,即可重複使用已複製的聲音。
目前 API
單次同步呼叫,回傳原始音訊位元組:
POST https://api.fish.audio/v1/tts
Authorization: Bearer ${FISH_AUDIO_API_KEY}
Content-Type: application/json
model: <後端模型> # HTTP 標頭選擇後端,例如 s1
後端模型是透過 model HTTP 標頭來選擇的,而非請求體內欄位。在 OpenMontage 中,這會對應到工具的 model 輸入。
後端模型
model 是必填的 — 沒有預設值。請傳遞下列其中一個:
s2.1-pro— 最新一代。最佳品質:支援行內情緒標籤、80 多種語言、多說話者。適用於英雄式旁白。s2.1-pro-free— 促銷免費使用 s2.1-pro。僅在促銷期間內,適用於草稿、樣本和驗證運行,費用為 $0。根據 fish.audio 公告:截至 2026 年 8 月 31 日免費,受合理使用條款約束,不提供 SLA/延遲保證,請求可能會被保留,且商業使用受到限制。切勿將生產環境或用戶旁白透過此模式處理。s2-pro— 第一代 S2 生成。穩定高品質,支援情緒標籤。s1— 前一代旗艦模型。為保持與現有整合的相容性而保留。
計費方式為按輸入文字的 UTF-8 位元組計費(非按字元)。中日韓(CJK)文字和表情符號的費用約為相同可見長度 ASCII 字元的 3-4 倍。目前定價:s1 / s2-pro / s2.1-pro = 每 100 萬位元組 $15 美元,s2.1-pro-free = 僅促銷期間 $0 美元(工具的 estimate_cost() 會在 2026 年 8 月 31 日後切換至付費的 s2.1-pro 費率)。在大量使用前,請前往 https://docs.fish.audio/developer-guide/models-pricing/pricing-and-rate-limits 確認最新定價。
行內情緒標籤(僅限 S2 模型)
s2-pro / s2.1-pro / s2.1-pro-free 會解析嵌入在文字中的行內情緒標籤:
- 像
[laugh]、[whispers]這類標籤能在句子中間改變語調。 - 範例:
"That's hilarious [laugh] but let me explain seriously." s1不解析情緒標籤 — 它們可能會被當作純文字唸出,因此在目標為 s1 時應移除這些標籤。
語音選擇(reference_id)
- 在 fish.audio 遊樂場中建立或挑選一個語音,然後複製其模型 ID。
- 將其作為
reference_id傳遞。當reference_id不存在時,選擇器的通用voice_id可作為別名使用。 - 若未提供
reference_id,fish.audio 將對所選模型使用其預設語音。
此工具不支援即時行內複製(每次請求上傳參考音訊 + 文字)— 請先在遊樂場中建立語音模型。
OpenMontage 使用方式
使用 TTS 選擇器生成:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "fish_audio",
"text": "Here's why compound interest quietly beats every get-rich-quick scheme.",
"model": "s1",
"reference_id": "<遊樂場語音模型 ID>",
"output_path": "projects/my-video/assets/audio/narration.mp3",
})
或直接呼叫提供者:
from tools.audio.fish_audio_tts import FishAudioTTS
result = FishAudioTTS().execute({
"text": "Short sample line for approval.",
"model": "s1",
"reference_id": "<遊樂場語音模型 ID>",
"output_path": "projects/my-video/assets/audio/fish_sample.mp3",
})
提供者會將音訊寫入 output_path,並回傳 data.output 以及解析後的 model 和 reference_id。
品質與延遲調校
latency:normal(預設,最佳品質)、balanced(稍快)或low(最快,犧牲少許品質)。normalize:預設為true;建議保持開啟,以便數字、日期和貨幣能自然朗讀。prosody:可選的{ "speed": 1.0, "volume": 0 },用於調整語速/音量。mp3_bitrate:128是不錯的預設值;若混音中音樂背景較重,可提高至192。temperature:預設為0.7。可提高至0.9左右以獲得更有表現力的朗讀(特別是在使用情緒標籤時建議這麼做);調低則可獲得更平穩、可預測的語調。top_p/repetition_penalty:通常保留預設值(0.7/1.2)即可。
建議工作流程
- 在進行完整的付費旁白生成前,先使用所選的
model+reference_id生成一段 10-15 秒的樣本。 - 請使用者確認語音自然度、情緒和語速。
- 只有在獲得批准後,再生成完整的旁白。
- 對於批次處理/本地化變體(成本考量),可先在
s2.1-pro-free上建立原型(促銷期間 $0;僅限非商業草稿),然後將最終版本升級為s2.1-pro。
故障排除
401 Unauthorized:FISH_AUDIO_API_KEY錯誤或缺失。402/ 付款錯誤:帳戶額度已用完。404/ 語音錯誤:reference_id錯誤或不屬於此帳戶。- 音訊空白/過短:請檢查
text是否為非空,以及normalize是否未將整個輸入清空。
安全性
切勿將 API 金鑰列印或寫入日誌、中繼資料、修補程式或專案產出物中。.env.example 應僅包含空的變數名稱。