> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API 接続説明書

> Fish music generation 集成指南 - XHuoAPI

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

## 申請手順

APIを使用するには、まず [Fish TTS API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) の対応ページからサービスを申請します。ページにアクセスしたら、「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は以下の通りです。

```shell theme={null}
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": "今天天気真好，我们一起出去散散步吧。"
  }'
```

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

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
```

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

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

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

```shell theme={null}
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` も含まれます。これにより、非同期結果と元のタスクを紐付けられます。

リクエスト例：

```shell theme={null}
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"
  }'
```

即時のレスポンス例：

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

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

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

また、[Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) を利用して `task_id` でステータスをポーリングすることも可能です。

## エラー処理

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

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

### エラー例

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

## まとめ

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