fish-audio-tts

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 header selects the backend, e.g. 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 をコピーします。
• その 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）のままにします。

推奨ワークフロー

1. 有料のナレーション全体を生成する前に、選択した model と reference_id で 10〜15 秒のサンプルを生成します。
2. 音声の自然さ、感情、ペースについてユーザーに確認してもらいます。
3. 承認を得てから、ナレーション全体を生成します。
4. コストが重要なバッチ処理やローカライズ版では、s2.1-pro-free で試作します（プロモーション期間中は $0、非商用の下書きのみ）。最終版は s2.1-pro に切り替えてください。

トラブルシューティング

• 401 Unauthorized：FISH_AUDIO_API_KEY が間違っているか、設定されていません。
• 402／支払いエラー：アカウントのクレジットがなくなっています。
• 404／無効な音声：reference_id が間違っているか、このアカウントが所有していません。
• 音声が空、または短い：text が空でないこと、normalize によって入力全体が除去されていないことを確認してください。

安全性

API キーをログ、メタデータ、パッチ、プロジェクトの成果物に出力したり書き込んだりしないでください。.env.example には、値が空の変数名のみを記載してください。