Fish Model Query API 連携説明

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

音色の作成については Fish Model Create API を参照してください。_id で単一音色の詳細を検索する場合は Fish Model Get API をご覧ください。

申請手順

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

公式APIとの違い

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

リクエスト例

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プラットフォームのページネーション構造をそのまま返します：

{
  "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 の reference_id フィールドの値として利用でき、このクローン音色を用いた音声合成に使用されます。

課金について

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

エラー処理

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 Model Query API は Fish Audio 公式と完全互換の音色検索機能を提供し、本プラットフォーム上で自身のクローン音色ライブラリを管理するのに利用できます。 Fish Model Get API と組み合わせることで、IDを指定して単一音色の詳細情報を取得可能です。

Documentation Index

​申請手順

​公式APIとの違い

​リクエスト例

​クエリパラメータ

​レスポンス例

​課金について

​エラー処理

​エラー応答例

​総括