Fish TTS API 接入說明

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

申請流程

要使用 API，需要先到 Fish TTS API 對應頁面申請對應的服務，進入頁面後，點擊「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 一個欄位，範例如下：

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": "今天天氣真好，我們一起出去散散步吧。"
  }'

回傳結果範例：

{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}

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

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

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

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 欄位，便於將異步結果與原始任務關聯。請求範例：

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"
  }'

立即返回的回應如下：

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

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

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

也可使用 Fish Tasks API 透過 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：伺服器內部錯誤，伺服器端出現問題。

錯誤回應範例

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

結論

Fish TTS API 與 Fish Audio 官方 OpenAPI 完全相容，可在零程式碼修改的前提下遷移既有專案，同時享有平台提供的統一授權、用量記帳以及異步回調能力。建議在生成長文本時優先使用異步回調，以避免長連線資源佔用。

Documentation Index

​申請流程

​與官方 API 的差異

​基本使用

​異步回調

​錯誤處理

​錯誤回應範例

​結論