Fish TTS API 接続説明書

本書では、Fish TTS API の接続説明について説明します。このインターフェースは Fish Audio公式OpenAPI と完全互換であり、元の https://api.fish.audio/v1/tts 呼び出しコードを https://api.xhuoapi.ai/v1/fish/tts に直接移行できます。認証情報を置き換えるだけで、リクエストボディの構造を変更する必要はありません。

申請手順

APIを使用するには、まず Fish TTS API の対応ページからサービスを申請します。ページにアクセスしたら、「Acquire」ボタンをクリックしてください。未ログインまたは未登録の場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。登録とログイン後、元のページに自動的に戻ります。初回申請時には無料枠が付与され、無料でAPIを利用できます。

公式APIとの違い

本APIは、Fish Audio公式のリクエスト・レスポンスフィールドを保持した上で、以下の少量の拡張を行っています。これにより、当プラットフォーム上での統合が容易になります。

認証方式：Authorization: Bearer {token} を使用します。ただし、{token} は当プラットフォームで申請したキーであり、Fish公式のキーではありません。
TTSモデルの選択：HTTPリクエストヘッダーの model で指定します。選択肢は s1 または s2-pro で、デフォルトは s2-pro。これはFish公式と一致します。
latency のデフォルト値：上流 /fish/v1/tts では latency 未指定時にエラーとなるため、本APIでは省略時に自動的に latency=normal を付与し、Fish公式の挙動と一致させています。
非同期コールバック（プラットフォーム拡張）：リクエストボディに callback_url を追加すると、APIは即座に {task_id, started_at} を返します。上流で実際に処理完了後、{audio_url, ...} をPOSTのJSON形式で callback_url に通知します。Fish公式APIにはこのフィールドはなく、追加しても当方の非同期処理をトリガーします。

上記以外の差異はなく、TTSリクエストボディのすべてのフィールド（text、reference_id、references、prosody、format、sample_rate、mp3_bitrate、chunk_length、temperature、top_p など）は、そのまま上流に透過され、公式ドキュメントと完全に一致します。

基本的な使い方

最小限のリクエストは text フィールドのみを送信します。例のcurlは以下の通りです。

curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天気真好，我们一起出去散散步吧。"
  }'

レスポンス例は以下の通りです。

{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}

このレスポンスはFish公式のフィールドをそのまま含みます。

audio_url：生成された音声のURL。直接ダウンロードまたは再生可能。
latency_ms（任意）：処理にかかった時間（ミリ秒）。

クローン音色を使用したい場合は、reference_id をリクエストボディに追加します。

curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天気真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'

非同期コールバック

長文生成には時間がかかる場合があり、長時間の接続維持はシステムリソースを消費します。そこで、本APIは非同期コールバック機能（Fish公式APIの拡張）を提供します。全体の流れは以下の通りです：クライアントはリクエストボディに callback_url を追加してリクエストを送信します。APIは即座に {task_id, started_at} を返します。実際に処理完了後、callback_url に {audio_url, ...} をPOSTし、task_id も含まれます。これにより、非同期結果と元のタスクを紐付けられます。リクエスト例：

curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天気真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

即時のレスポンス例：

{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}

しばらく待つと、callback_url に以下の結果が通知されます。

{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}

また、Fish Tasks API を利用して task_id でステータスをポーリングすることも可能です。

エラー処理

本APIのエラー応答はFish公式のHTTPステータスコードを保持しつつ、レスポンスボディはプラットフォーム共通のフォーマットを採用しています。

400 token_mismatched：不正リクエスト。パラメータ不足または無効。
400 api_not_implemented：不正リクエスト。パラメータ不足または無効。
401 invalid_token：認証失敗。トークン無効または未設定。
429 too_many_requests：リクエスト過多。レート制限超過。
500 api_error：サーバ内部エラー。

エラー例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

まとめ

Fish TTS APIはFish Audio公式OpenAPIと完全互換であり、コードの改修なしに既存プロジェクトを移行可能です。同時に、プラットフォームが提供する認証、利用量管理、非同期コールバックなどの機能も利用できます。長文生成時は、長時間の接続維持を避けるために非同期コールバックの利用を推奨します。

Documentation Index

​申請手順

​公式APIとの違い

​基本的な使い方

​非同期コールバック

​エラー処理

​エラー例

​まとめ