fish-audio-tts 是 OpenMontage 项目中的一个文本转语音(TTS)工具,用于调用 fish.audio 的语音合成服务,生成富有表现力、支持多语言的旁白,并可通过 reference_id 复用已克隆的声音。
用途 该工具适用于用户希望使用 fish.audio(S1 / S2 代模型)生成旁白,并复用克隆声音的场景。它通过单次同步调用返回原始音频字节。
前置条件 需要在 .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),而不是请求体字段。在 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 为每 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": "<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)。
推荐工作流
- 在完整付费旁白前,用所选模型 + reference_id 生成 10-15 秒样本。
- 请用户确认声音自然度、情感和节奏。
- 仅在批准后生成完整旁白。
- 对于成本敏感的批量/本地化变体,先在 s2.1-pro-free 上原型(促销窗口 $0;仅限非商业草稿),最终升级到 s2.1-pro。
故障排查
- 401 Unauthorized:FISH_AUDIO_API_KEY 错误或缺失。
- 402 / 支付错误:账户余额耗尽。
- 404 / 声音错误:reference_id 错误或不属于该账户。
- 音频为空/过短:检查文本非空,且 normalize 未剥离整个输入。
安全 切勿将 API 密钥打印或写入日志、元数据、补丁或项目产物。.env.example 应只包含空变量名。