> ## 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 Model Query API 連携説明

> Fish music generation 集成指南 - XHuoAPI

本稿では Fish Model Query API（`GET /fish/model`）の連携説明を紹介します。本APIは [Fish Audio 公式 OpenAPI](https://docs.fish.audio/resources/api-reference/model) と完全互換であり、現在のアカウントまたはプラットフォーム全体で閲覧可能なクローン音色リストを**ページネーションで検索**するために使用されます。

> 音色の作成については [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) を参照してください。`_id` で単一音色の詳細を検索する場合は [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9) をご覧ください。

## 申請手順

APIを利用するには、まず [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) の該当ページでサービスを申請してください。ページにアクセスしたら「Acquire」ボタンをクリックします。

未ログインまたは未登録の場合は自動的にログインページにリダイレクトされ、登録とログインを促されます。ログイン・登録後は自動的に元のページに戻ります。

初回申請時には無料枠が付与され、本APIを無料で利用可能です。

## 公式APIとの違い

* **認証方式**：`Authorization: Bearer {token}` を使用します。`{token}` は本プラットフォームで申請したキーです。
* **レスポンス構造**：Fish上流のページネーションレスポンスをそのまま透過し、プラットフォーム独自のenvelopeラッピングは行いません。エラー時は `{success:false, error:{code,message}, trace_id}` のプラットフォーム標準構造を使用します。

## リクエスト例

```shell theme={null}
curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'
```

## クエリパラメータ

Fish公式と同様です：

* `page_size`：1ページあたりの件数。デフォルトは10。
* `page_number`：ページ番号。1から開始。
* `title`：タイトルの部分一致検索。
* `tag`：タグによるフィルタリング。
* `self`：`true` を指定すると、現在のアカウントが作成した音色のみを返します。
* `author_id`：作成者によるフィルタリング。
* `language`：音色の言語によるフィルタリング。
* `title_language`：タイトルの言語によるフィルタリング。

## レスポンス例

成功時はFishプラットフォームのページネーション構造をそのまま返します：

```json theme={null}
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "我的克隆音色",
      "description": "用一段播客录音克隆的音色",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}
```

返却される `_id` は後続の [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) の `reference_id` フィールドの値として利用でき、このクローン音色を用いた音声合成に使用されます。

## 課金について

本APIは課金対象外です。音色リストのページネーション検索は無料で利用可能であり、新規音色作成時に `POST /fish/model` のリクエストボディに `voices` フィールドを含めた場合のみ課金されます。

## エラー処理

* `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 Model Query API は Fish Audio 公式と完全互換の音色検索機能を提供し、本プラットフォーム上で自身のクローン音色ライブラリを管理するのに利用できます。 [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9) と組み合わせることで、IDを指定して単一音色の詳細情報を取得可能です。