Skip to main content
本文將介紹 Fish Model API 的對接說明，該介面與 Fish Audio 官方 OpenAPI 完全相容，包含：
  • POST /fish/model：基於音頻樣本建立一個新的克隆音色（Voice Model）。
  • GET /fish/model：分頁查詢當前帳號或全平台可見的音色列表。

​
申請流程

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

​
與官方 API 的差異

  • 鑑權方式：使用 Authorization: Bearer {token}，其中 {token} 是在本平台申請的密鑰。
  • 建立模型時的樣本上傳：本介面當前僅支援以 JSON 形式提交，並透過 voices 欄位傳入音頻樣本的 URL。Fish 官方支援 multipart/msgpack 直接上傳二進位，本平台暫未實現，URL 形式覆蓋了大約 80% 的常見場景。
  • 回應結構：POST /fish/model 與 GET /fish/model 都直接透傳 Fish 上游的回應，不做平台 envelope 包裝，錯誤時使用 {success:false, error:{code,message}, trace_id} 的平台標準結構。

​
建立音色（POST /fish/model）

最小建立請求需要 title 與 voices 兩個欄位。voices 是音頻樣本 URL 列表，建議每個檔案 30 秒以上，取樣率 16k 及以上。
成功回應直接返回 Fish 平台的 ModelEntity 物件：
返回的 _id 即可作為後續 POST /fish/tts 中 reference_id 欄位的值，用於使用該克隆音色進行語音合成。

​
查詢音色列表（GET /fish/model）

可用查詢參數（與 Fish 官方一致）：
  • page_size：每頁條數，預設 10。
  • page_number：頁碼，從 1 開始。
  • title：按標題模糊搜尋。
  • tag：按標籤過濾。
  • self：傳 true 時僅返回當前帳號建立的音色。
  • author_id：按建立者過濾。
  • language：按音色語種過濾。
  • title_language：按標題語種過濾。
成功回應同樣直接透傳 Fish 平台的分頁結構：

​
計費說明

本介面僅在「建立音色」時計費（POST /fish/model 且請求體攜帶 voices 欄位），「查詢音色列表」（GET /fish/model）不計費。

​
錯誤處理

  • 400 token_mismatched：Bad request，可能因缺少或無效參數。
  • 400 api_not_implemented：Bad request，可能因缺少或無效參數。
  • 401 invalid_token：Unauthorized，無效或缺少授權令牌。
  • 429 too_many_requests：請求過多，已超過速率限制。
  • 500 api_error：內部伺服器錯誤，伺服器端發生問題。

​
錯誤回應範例

​
結論

Fish Model API 與 Fish Audio 官方 OpenAPI 的 ModelEntity 介面完全相容，可在零程式碼改動的前提下遷移已有的克隆音色管理程式碼。建立出的音色 _id 可以直接餵給 Fish TTS API 的 reference_id 欄位進行語音合成。