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

> Fish music generation 集成指南 - XHuoAPI

本稿では Fish Model Get API（`GET /fish/model/{id}`）の接続説明を紹介します。本APIは [Fish Audio 公式 OpenAPI](https://docs.fish.audio/resources/api-reference/model) と完全互換で、**音色IDによる単一クローン音色の詳細情報取得**に使用されます。

> 音色作成は [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) を、ページネーション付きリスト検索は [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) を参照してください。

## 申請手順

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

未ログインまたは未登録の場合は、自動的にログインページに遷移し、登録とログインを促されます。ログイン後は自動的に元のページに戻ります。

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

## 公式APIとの違い

* **認証方式**：`Authorization: Bearer {token}` を使用し、`{token}` は本プラットフォームで申請したキーです。
* **レスポンス構造**：Fish上流の ModelEntity オブジェクトをそのまま透過し、プラットフォーム独自のenvelopeラッピングはしません。エラー時は `{success:false, error:{code,message}, trace_id}` のプラットフォーム標準構造を使用します。
* **パスパラメータ**：`{id}` は音色の `_id` で、[Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) の作成時に返されるか、[Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) のページネーション検索で取得可能です。

## リクエスト例

```shell theme={null}
curl 'https://api.xhuoapi.ai/v1/fish/model/d7900c21663f485ab63ebdb7e5905036' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}'
```

URLパスの `{id}` を具体的な音色IDに置き換えるだけで、クエリパラメータやリクエストボディは不要です。

## レスポンス例

成功時は 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": [
    {
      "audio": "https://example.com/sample-voice.mp3",
      "text": ""
    }
  ],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "default_text": "",
  "default_mode": "fast",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "unliked": false,
  "liked": false,
  "marked": false,
  "author": {
    "_id": "00000000000000000000000000000000",
    "nickname": "",
    "avatar": ""
  }
}
```

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

## 課金説明

本APIは課金対象外です。IDによる音色詳細取得は無料操作であり、新規音色作成時に `POST /fish/model` のリクエストボディに `voices` フィールドを含めた場合のみ課金されます。

## エラー処理

* `400 token_mismatched`：リクエストパラメータの不足または不正。
* `400 api_not_implemented`：リクエストメソッドまたはパラメータが未対応。
* `401 invalid_token`：認証情報の欠如または無効。
* `404 not_found`：指定した `_id` の音色が存在しないか、現在のアカウントで閲覧不可。
* `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 Get API は Fish Audio 公式と完全互換の単一音色詳細取得機能を提供します。音色IDを取得後、本APIで ModelEntity オブジェクト（サンプル、状態、可視性、統計情報含む）を取得し、[Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) と組み合わせてクローン＋合成のエンドツーエンド処理を実現できます。