> ## 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 API 接続説明

> Fish music generation 集成指南 - XHuoAPI

本稿では Fish Model API の接続説明を紹介します。本インターフェースは [Fish Audio 公式 OpenAPI](https://docs.fish.audio/resources/api-reference/model) と完全互換で、以下を含みます：

* `POST /fish/model`：音声サンプルに基づいて新しいクローン音色（Voice Model）を作成します。
* `GET /fish/model`：現在のアカウントまたは全プラットフォームで閲覧可能な音色リストをページネーションで取得します。

## 申請手順

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

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録およびログインを促されます。ログイン・登録後は自動的に元のページに戻ります。

初回申請時には無料クレジットが付与され、この API を無料で利用可能です。

## 公式 API との違い

* **認証方式**：`Authorization: Bearer {token}` を使用し、`{token}` は本プラットフォームで申請したキーです。
* **モデル作成時のサンプルアップロード**：本インターフェースは現在 JSON 形式での提出のみ対応し、`voices` フィールドで音声サンプルの URL を渡します。Fish 公式は multipart/msgpack によるバイナリ直接アップロードをサポートしていますが、本プラットフォームでは未実装です。URL 形式は約 80% の一般的なケースをカバーします。
* **レスポンス構造**：`POST /fish/model` と `GET /fish/model` は Fish 上流のレスポンスをそのまま透過し、プラットフォームのエンベロープ包装は行いません。エラー時は `{success:false, error:{code,message}, trace_id}` のプラットフォーム標準構造を使用します。

## 音色作成（POST /fish/model）

最小限の作成リクエストには `title` と `voices` の2つのフィールドが必要です。`voices` は音声サンプルの URL リストで、各ファイルは30秒以上、サンプリングレート16k以上を推奨します。

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "私のクローン音色",
    "description": "ポッドキャスト録音からクローンした音色",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
```

成功レスポンスは Fish プラットフォームの ModelEntity オブジェクトを直接返します：

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "私のクローン音色",
  "description": "ポッドキャスト録音からクローンした音色",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
```

返却される `_id` は、後続の `POST /fish/tts` の `reference_id` フィールドの値として使用でき、このクローン音色を用いた音声合成に利用可能です。

## 音色リストの取得（GET /fish/model）

```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
}
```

## 課金について

本インターフェースは「音色作成時」（`POST /fish/model` かつリクエストボディに `voices` フィールドがある場合）のみ課金対象で、「音色リスト取得」（`GET /fish/model`）は課金されません。

## エラー処理

* `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 API は Fish Audio 公式 OpenAPI の ModelEntity インターフェースと完全互換であり、既存のクローン音色管理コードをゼロコード変更で移行可能です。作成した音色の `_id` はそのまま [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) の `reference_id` フィールドに渡して音声合成に利用できます。