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

# Fish Model Query API 接続説明

> Fish voice generation API guide - Ace Data Cloud

本インターフェースは [Fish Audio 公式 Model API](https://docs.fish.audio/resources/api-reference/model) に基づいており、**Fish 公共音色ライブラリまたは現在のアカウント下のクローン音色をページング検索するために使用されます**。アドレスは `GET https://api.acedata.cloud/fish/model` です。

> 音色を作成するには [Fish Model Create API](https://platform.acedata.cloud/documents/fish-model) を参照してください； `_id` による単一音色の詳細を取得するには [Fish Model Get API](https://platform.acedata.cloud/documents/fish-model-get) を参照してください。

## 申請プロセス

Fish Model API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます；クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。

> 📘 完全なドキュメント：[Fish Model API →](https://platform.acedata.cloud/services/fish)

## クエリパラメータ

| パラメータ | タイプ | デフォルト | 説明 |
| - | - | - | - |
| `page_size` | integer | 10 | 1ページあたりのアイテム数。 |
| `page_number` | integer | 1 | 1から始まるページ番号。 |
| `title` | string | — | タイトルによるあいまい検索。 |
| `tag` | string | — | 単一のタグによるフィルタリング。 |
| `self` | boolean | — | `true` の場合、現在のアカウントが作成した音色のみを返します。 |
| `author_id` | string | — | 上流ユーザーの `_id` によるフィルタリング。 |
| `language` | string | — | 音色の言語によるフィルタリング、例： `en`、`zh`、`es`。 |
| `title_language` | string | — | タイトルの言語によるフィルタリング。 |
| `sort_by` | string | — | ソートフィールド、上流と一致、例： `created_at`、`task_count`。 |

> パラメータ名は上流の `GET https://api.fish.audio/model` と完全に一致しており、詳細は [Fish 公式ドキュメント](https://docs.fish.audio/resources/api-reference/model) を参照してください。

## 例 1：デフォルトのページング（`page_size` による）

```shell theme={null}
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'
```

返却（実測、公共ライブラリの総数は約 180 万件；可読性のため、以下の例では一部の長いフィールドを省略）：

```json theme={null}
{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "落ち着いた、精神的なトーンの成熟した権威ある男性の声...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}
```

## 例 2：タイトルによるあいまい検索（`title`）

```shell theme={null}
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'
```

返却（実測）：

```json theme={null}
{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}
```

注意 `title` は「グローバルあいまい一致」であり、Fish 公共ライブラリのすべての音色にヒットします（自分のものだけではありません）。

## 例 3：自分が作成した音色のみをリストアップ（`self=true`）

```shell theme={null}
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'
```

返却（実測、現在のアカウント下には 1 つの音色のみ）：

```json theme={null}
{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "api.acedata.cloud からのスモークテスト",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "text": "師父、[語気を強めて]私は本当にこの山の冷たい日々にうんざりしています！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}
```

`self=true` はフィルタリングで `author_id == 現在のアカウント上流 ID` を限定することと同等であり、一般的な「自分の音色リスト」への入り口です。

## 例 4：言語 + タグによるフィルタリング

```shell theme={null}
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'
```

> 上流は、タグ辞書にない `tag` に対しても結果を返しますが、マッチングは比較的緩やかです；ヒット数が 0 の場合は、`title` のあいまい検索を使用することをお勧めします。

## 応答フィールド

`items[]` の各項目は完全な ModelEntity オブジェクトで、一般的なフィールド：

| フィールド | タイプ | 説明 |
| - | - | - |
| `_id` | string | 音色 ID、`/fish/tts` の `reference_id` の値として使用されます。 |
| `type` | string | モデルタイプ、通常は `tts`。 |
| `title` | string | 音色名。 |
| `description` | string | 音色の説明。 |
| `state` | string | トレーニング状態：`trained` は使用可能を示します。 |
| `tags` | string\[] | 公共ライブラリのタグ。 |
| `languages` | string\[] | 音色が得意とする言語。 |
| `visibility` | string | `public` または `private`。 |
| `samples` | object\[] | プリセットサンプル（`audio` 直リンクを含む）。 |
| `like_count` | integer | 公共ライブラリのいいね数。 |
| `task_count` | integer | 過去の合成回数。 |
| `author` | object | 上流の著者情報：`_id` / `nickname` / `avatar`。 |
| `total`（トップレベル） | integer | 条件を満たす総件数。 |
| `has_more` | boolean? | 上流のページング指示、`null` の可能性があります。総ページ数は `total / page_size` で計算することをお勧めします。 |

## 課金説明

このインターフェースは課金されません——音色リストのページングクエリは無料操作です。音色の作成（[Fish Model Create](https://platform.acedata.cloud/documents/fish-model)）も同様に無料で、費用は [Fish TTS](https://platform.acedata.cloud/documents/fish-tts) を呼び出して音声を合成する際に使用量に応じて発生します。

## エラーハンドリング

* `400 token_mismatched`：リクエストパラメータが欠落または不正です。
* `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 公共ライブラリから音色を選択して `/fish/tts` の `reference_id` に供給するには、まずこのインターフェースを使用して `title` / `tag` / `language` で検索し、目的の `_id` を特定し、次に [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get) を使用してサンプルを試聴します。自分が作成した音色をリストアップするには、`self=true` を渡すだけです。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.