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 Voices Generation API 對接說明，它是可以透過輸入音頻連結來創建自己的音色。
申請流程
要使用 API，需要先到 Fish Voices Generation API 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕，如圖所示：
如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。
在首次申請時會有免費額度贈送，可以免費使用該 API。
基本使用
首先先了解下基本的使用方式，就是輸入音色的音頻連結 voice_url，便可獲得處理後的結果，具體的內容如下：
可以看到這裡我們設定了 Request Headers，包括：
accept：想要接收怎樣格式的響應結果，這裡填寫為 application/json，即 JSON 格式。authorization：調用 API 的密鑰，申請之後可以直接下拉選擇。
另外設定了 Request Body，包括：
voice_url：上傳的音色音頻連結。title：該音色的標題信息。image_urls：該音色的封面圖片。description：該音色的描述信息。callback_url：需要回調結果的URL。
選擇之後，可以發現右側也生成了對應代碼，如圖所示：
點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果：
{
"success": true,
"task_id": "b01db503-dd9e-4f92-861a-344f14756217",
"trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
"data": {
"_id": "d5d21261512b4852b9ccd709facf93f3",
"type": "tts",
"title": "test",
"description": "test",
"cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
"train_mode": "fast",
"state": "trained",
"tags": [],
"samples": [
{
"title": "Default Sample",
"text": "透過長期觀察發現，珊瑚礁生態系統中的魚類具有複雜的群體行為模式。它們利用色彩變化和特定的游動姿態來傳遞信息，這種精密的非語言交流系統展現了海洋生物的適應智慧。",
"task_id": "4ae961828fc94c07b2103dc039a8466b",
"audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
}
],
"created_at": "2025-09-21T07:29:41.058506Z",
"updated_at": "2025-09-21T07:29:41.057917Z",
"languages": [
"zh"
],
"visibility": "public",
"lock_visibility": false,
"default_text": "透過長期觀察發現，珊瑚礁生態系統中的魚類具有複雜的群體行為模式。它們利用色彩變化和特定的游動姿態來傳遞信息，這種精密的非語言交流系統展現了海洋生物的適應智慧。",
"like_count": 0,
"mark_count": 0,
"shared_count": 0,
"task_count": 0,
"unliked": false,
"liked": false,
"marked": false,
"author": {
"_id": "7ecad23df62a4174acd6a2a6cb5201ee",
"nickname": "Matthew Garcia",
"avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
}
}
}
success，此時音色創建任務的狀態情況。
data，音樂任務的結果
_id，此時音色生成任務ID，後續是用此ID進行克隆聲音的創作。title，音色的標題。image_url，音色的封面信息。description，音色的描述信息。train_mode，此時音色生成任務所採用的模式。tags，音色的風格。default_text，此時音色生成任務的聲音文本信息。
可以看到我們得到了滿意的音色信息，我們只需要根據結果中 data 的_id進行克隆聲音任務即可。
另外如果想生成對應的對接代碼，可以直接複製生成，例如 CURL 的代碼如下：
curl -X POST 'https://api.xhuoapi.ai/v1/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
"title": "test",
"description": "test"
}'
異步回調
由於 Fish Voices Generation API生成的時間相對較長，大約需要 1-2 分鐘，如果 API 長時間無響應，HTTP 請求會一直保持連接，導致額外的系統資源消耗，所以本 API 也提供了異步回調的支持。
整體流程是：客戶端發起請求的時候，額外指定一個 callback_url 字段，客戶端發起 API 請求之後，API 會立馬返回一個結果，包含一個 task_id 的字段信息，代表當前的任務 ID。當任務完成之後，生成任務的結果會透過 POST JSON 的形式發送到客戶端指定的 callback_url，其中也包括了 task_id 字段，這樣任務結果就可以透過 ID 關聯起來了。
下面我們通過示例來了解下具體怎樣操作。
首先，Webhook 回調是一個可以接收 HTTP 請求的服務，開發者應該替換為自己搭建的 HTTP 伺服器的 URL。此處為了方便演示，使用一個公開的 Webhook 樣例網站 https://webhook.site/，打開該網站即可得到一個 Webhook URL，如圖所示：
將此 URL 複製下來，就可以作為 Webhook 來使用，此處的樣例為 https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34。
接下來，我們可以設定字段 callback_url 為上述 Webhook URL，同時填入相應的參數，具體的內容如圖所示：
點擊運行，可以發現會立即得到一個結果，如下：
{
"task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34 上觀察到生成任務的結果，如圖所示：
內容如下：
{
"success": true,
"task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
"trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
"data": {
"_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
"type": "tts",
"title": "test",
"description": "test",
"cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
"train_mode": "fast",
"state": "trained",
"tags": [],
"samples": [
{
"title": "Default Sample",
"text": "海豚透過回聲定位系統在海洋中導航，這種精確的聲波技術讓它們能夠探測周圍環境，尋找食物和避開危險。這不僅展現了海洋生物的適應能力，也揭示了大自然的奇妙設計。",
"task_id": "68cdda24d26e4794bae177e20da740db",
"audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
}
],
"created_at": "2025-09-21T07:36:20.200865Z",
"updated_at": "2025-09-21T07:36:20.200353Z",
"languages": [
"zh"
],
"visibility": "public",
"lock_visibility": false,
"default_text": "海豚透過回聲定位系統在海洋中導航，這種精確的聲波技術讓它們能夠探測周圍環境，尋找食物和避開危險。這不僅展現了海洋生物的適應能力，也揭示了大自然的奇妙設計。",
"like_count": 0,
"mark_count": 0,
"shared_count": 0,
"task_count": 0,
"unliked": false,
"liked": false,
"marked": false,
"author": {
"_id": "7ecad23df62a4174acd6a2a6cb5201ee",
"nickname": "Matthew Garcia",
"avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
}
}
}
task_id 欄位，其他的欄位都和上文類似，通過該欄位即可實現任務的關聯。
錯誤處理
在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：
400 token_mismatched：錯誤請求，可能是由於缺少或無效的參數。400 api_not_implemented：錯誤請求，可能是由於缺少或無效的參數。401 invalid_token：未授權，無效或缺少授權令牌。429 too_many_requests：請求過多，您已超過速率限制。500 api_error：內部伺服器錯誤，伺服器出現問題。
錯誤響應示例
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
