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

> Fish music generation 集成指南 - XHuoAPI

本文將介紹 Fish TTS API 的接入說明，該接口與 [Fish Audio 官方 OpenAPI](https://docs.fish.audio/text-to-speech/text-to-speech) 完全相容，可直接將原本調用 `https://api.fish.audio/v1/tts` 的程式碼遷移到 `https://api.xhuoapi.ai/v1/fish/tts`，僅需替換授權資訊即可，無需修改請求體結構。

## 申請流程

要使用 API，需要先到 [Fish TTS API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) 對應頁面申請對應的服務，進入頁面後，點擊「Acquire」按鈕。

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊後會自動返回當前頁面。

在首次申請時會有免費額度贈送，可以免費使用該 API。

## 與官方 API 的差異

本 API 在保留 Fish Audio 官方請求和響應欄位的基礎上做了如下少量增強，方便在我們的平台上更好地整合：

* **授權方式**：使用 `Authorization: Bearer {token}`，其中 `{token}` 是在本平台申請的密鑰，而非 Fish 官方密鑰。
* **TTS 模型選擇**：透過 HTTP 請求標頭 `model` 指定，可選 `s1` 或 `s2-pro`，預設值為 `s2-pro`。這與 Fish 官方一致。
* **`latency` 預設值**：上游 `/fish/v1/tts` 在未傳 `latency` 時會返回錯誤，本接口在缺省時會自動補上 `latency=normal`，與 Fish 官方預設行為保持一致。
* **異步回調（平台擴展）**：在請求體中傳入額外的 `callback_url` 欄位時，接口會立即返回 `{task_id, started_at}`，待上游真正完成後，將完整的 `{audio_url, ...}` 結果以 POST JSON 形式回調到該 URL。Fish 官方接口不支援此欄位，傳入它僅會觸發我方的異步流程。

除上述差異外，TTS 請求體中的所有欄位（`text`、`reference_id`、`references`、`prosody`、`format`、`sample_rate`、`mp3_bitrate`、`chunk_length`、`temperature`、`top_p` 等）皆直接透傳給上游，行為與官方文件完全一致。

## 基本使用

最小的請求只需傳 `text` 一個欄位，範例如下：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天氣真好，我們一起出去散散步吧。"
  }'
```

回傳結果範例：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
```

回傳結果直接是 Fish 官方的欄位，包括：

* `audio_url`：生成的音訊 URL，可直接下載或播放。
* `latency_ms`（可選）：上游處理耗時，毫秒。

如果需要使用克隆音色，可以在請求體中加入 `reference_id`：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天氣真好，我們一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'
```

## 異步回調

由於 Fish TTS 在長文本場景下生成耗時可能較長，長連線保持會消耗系統資源，本 API 提供了異步回調能力（這是相較 Fish 官方接口的擴展）。

整體流程為：客戶端發起請求時在請求體中額外指定 `callback_url` 欄位，API 會立即返回包含 `task_id` 的回應；上游真正生成完成後，最終的 `audio_url` 等欄位會以 POST JSON 形式發送到 `callback_url`，並在請求體中帶上同一個 `task_id` 欄位，便於將異步結果與原始任務關聯。

請求範例：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天氣真好，我們一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

立即返回的回應如下：

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
```

稍後，`callback_url` 會收到完整結果：

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

也可使用 [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) 透過 `task_id` 主動輪詢任務狀態。

## 錯誤處理

本接口的錯誤回應保留了 Fish 官方的 HTTP 狀態碼，但回應體使用平台統一格式，以便與 `/fish/audios`、`/fish/voices` 系列保持一致：

* `400 token_mismatched`：Bad request，可能缺少或參數無效。
* `400 api_not_implemented`：Bad request，可能缺少或參數無效。
* `401 invalid_token`：未授權，授權 token 無效或缺失。
* `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 TTS API 與 Fish Audio 官方 OpenAPI 完全相容，可在零程式碼修改的前提下遷移既有專案，同時享有平台提供的統一授權、用量記帳以及異步回調能力。建議在生成長文本時優先使用異步回調，以避免長連線資源佔用。