Fish Model Get API 對接說明

本文將介紹 Fish Model Get API（GET /fish/model/{id}）的對接說明，該接口與 Fish Audio 官方 OpenAPI 完全兼容，用於按音色 ID 查詢單個克隆音色的完整詳情。

創建音色請參考 Fish Model Create API，分頁列表查詢請參考 Fish Model Query API。

申請流程

要使用 API，需要先到 Fish Model API 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕。如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。在首次申請時會有免費額度贈送，可以免費使用該 API。

與官方 API 的差異

鑑權方式：使用 Authorization: Bearer {token}，其中 {token} 是在本平台申請的密鑰。
響應結構：直接透傳 Fish 上游的 ModelEntity 對象，不做平台 envelope 包裝；錯誤時使用 {success:false, error:{code,message}, trace_id} 的平台標準結構。
路徑參數：{id} 即音色的 _id，可由 Fish Model Create API 創建時返回，也可由 Fish Model Query API 分頁查詢時獲得。

請求示例

curl 'https://api.acedata.cloud/fish/model/d7900c21663f485ab63ebdb7e5905036' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}'

只需要把 URL 路徑裡的 {id} 替換成具體音色 ID，無需任何查詢參數或請求體。

響應示例

成功響應直接透傳 Fish 平台的 ModelEntity 對象：

{
  "_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 中 reference_id 欄位的值，用於使用該克隆音色進行語音合成。

計費說明

本接口不計費——按 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：伺服器內部錯誤。

錯誤響應示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

Fish Model Get API 提供與 Fish Audio 官方完全兼容的單個音色詳情查詢能力。在拿到音色 ID 後，可以用本接口拉取完整的 ModelEntity 對象（包括樣本、狀態、可見性、統計欄位等），再配合 Fish TTS API 完成端到端的克隆 + 合成流程。

​申請流程

​與官方 API 的差異

​請求示例

​響應示例

​計費說明

​錯誤處理

​錯誤響應示例

​結論