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: <backend 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 文本和 emoji 的成本是相同可见长度 ASCII 字符的 3-4 倍。当前列表定价:s1 / s2-pro / s2.1-pro = 每 1M 字节 $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": "<playground voice model 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": "<playground voice model 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 应仅包含空的变量名。