> ## 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 API 對接說明

> Fish music generation 集成指南 - XHuoAPI

本文將介紹 Fish Model API 的對接說明，該介面與 [Fish Audio 官方 OpenAPI](https://docs.fish.audio/resources/api-reference/model) 完全相容，包含：

* `POST /fish/model`：基於音頻樣本建立一個新的克隆音色（Voice Model）。
* `GET /fish/model`：分頁查詢當前帳號或全平台可見的音色列表。

## 申請流程

要使用 API，需要先到 [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) 對應頁面申請對應的服務，進入頁面之後，點擊「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 及以上。

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客錄音克隆的音色",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
```

成功回應直接返回 Fish 平台的 ModelEntity 物件：

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "我的克隆音色",
  "description": "用一段播客錄音克隆的音色",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
```

返回的 `_id` 即可作為後續 `POST /fish/tts` 中 `reference_id` 欄位的值，用於使用該克隆音色進行語音合成。

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

```shell theme={null}
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 平台的分頁結構：

```json theme={null}
{
  "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
}
```

## 計費說明

本介面僅在「建立音色」時計費（`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`：內部伺服器錯誤，伺服器端發生問題。

### 錯誤回應範例

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

## 結論

Fish Model API 與 Fish Audio 官方 OpenAPI 的 ModelEntity 介面完全相容，可在零程式碼改動的前提下遷移已有的克隆音色管理程式碼。建立出的音色 `_id` 可以直接餵給 [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) 的 `reference_id` 欄位進行語音合成。