Fish Model Query API 串接說明

本介面基於 Fish Audio 官方 Model API，用於分頁查詢 Fish 公共音色庫或目前帳號下的克隆音色。網址為 GET https://api.acedata.cloud/fish/model。

建立音色請參考 Fish Model Create API；依 _id 查詢單一音色詳細資訊請參考 Fish Model Get API。

申請流程

若要使用 Fish Model API，首先前往 Ace Data Cloud 控制台取得您的 API Token，留作備用。

如果您尚未登入或註冊，會自動跳轉至登入頁面邀請您註冊與登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台儲值通用餘額。

📘 完整文件：Fish Model API →

查詢參數

參數	類型	預設	說明
`page_size`	integer	10	每頁筆數。
`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	—	排序欄位；`self=true` 時支援 `created_at`、`task_count`。

參數命名與上游 GET https://api.fish.audio/model 完全一致，詳見 Fish 官方文件。

範例 1：預設翻頁（依 `page_size`）

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

回傳（實測，公共庫總量約 180 萬筆；為了可讀性，下例省略了部分較長欄位）：

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "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`）

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

回傳（實測）：

{
  "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`）

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

回傳範例：

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from 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": false
}

self=true 會依實際呼叫帳號列出透過本平台建立並儲存的音色；同一帳號使用不同 API Token 建立的音色也會一併列出。結果依建立時間倒序分頁，author_id 可進一步篩選這些音色的作者 ID。此參數僅篩選列表，音色仍公開可用。 self=true 不支援 title_language；如需依標題語種搜尋，請查詢公共音色庫。

範例 4：依語種 + 標籤篩選

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?	`self=true` 時為布林值；公共音色庫查詢可能為 `null`。

計費說明

本介面不計費——分頁查詢音色列表是免費操作。建立音色（Fish Model Create）同樣免費，費用僅在呼叫 Fish TTS 合成語音時依用量產生。

錯誤處理

400 token_mismatched：請求參數缺失或不合法。
401 invalid_token：驗證 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 公共庫挑選音色提供給 /fish/tts 的 reference_id，先使用本介面搭配 title / tag / language 檢索，定位到目標 _id，再使用 Fish Model Get 取得樣本試聽。要列出自己建立的音色，傳入 self=true 即可。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Fish Model Query API 串接說明

申請流程

查詢參數

範例 1：預設翻頁（依 `page_size`）

範例 2：依標題模糊搜尋（`title`）

範例 3：僅列出自己建立的音色（`self=true`）

範例 4：依語種 + 標籤篩選

回應欄位

計費說明

錯誤處理

結論

​申請流程

​查詢參數

​範例 1：預設翻頁（依 page_size）

​範例 2：依標題模糊搜尋（title）

​範例 3：僅列出自己建立的音色（self=true）

​範例 4：依語種 + 標籤篩選

​回應欄位

​計費說明

​錯誤處理

​結論

申請流程

查詢參數

範例 1：預設翻頁（依 `page_size`）

範例 2：依標題模糊搜尋（`title`）

範例 3：僅列出自己建立的音色（`self=true`）

範例 4：依語種 + 標籤篩選

回應欄位

計費說明

錯誤處理

結論