跳轉到主要內容

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 Query API（GET /fish/model）的對接說明，該接口與 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：每頁條數，預設 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 欄位的值，用於使用該克隆音色進行語音合成。

​
計費說明

本接口不計費——分頁查詢音色列表是免費操作，僅 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 拿到單個音色的完整詳情。