非同步作業

使用非同步 TTS 作業進行長文字、批次產生、Webhook 式工作流程和 UI 流程，使用者可以在音訊仍在處理時離開頁面。

建立工作

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

＃＃＃要求

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1,
  "pitch": 0,
  "language": "auto",
  "emotion": "neutral",
  "instruction": "Speak naturally",
  "textNormalization": true
}

將文字哈希、請求的語音和傳回的任務 ID 保留在資料庫中。如果您的工作執行緒在建立後崩潰，則透過任務 ID 進行輪詢比建立第二個作業更安全。

範例使用公共系統測試語音00a1b221-6137-4b73-ad62-b0cbce134167。驗證連線後將其替換為您首選的語音 ID。

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'

回覆

建立端點傳回 202 Accepted。開始輪詢前請儲存 task.id。

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

找工作

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

狀態值為 pending、processing、success、partial_fail 和 fail。

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

task.segments[].playbackUrl 也需要相同標頭。不要為了恢復下載而建立另一個工作。

找回任務 ID

如果建立請求已到達伺服器，但客戶端未收到 202 Accepted，請先列出最近的任務：

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

結果依建立時間由新到舊排列。可用 createdAt、textFingerprint、voiceId 和 engineModelId 比對本機請求。支援 page、limit（最大 100）、status 和 ISO 8601 格式的 createdAfter。列表只傳回文字預覽，不會傳回完整文字。找到 taskId 後，繼續輪詢原任務；查詢列表不會消耗 API 額度。

計費和積分

伺服器接受工作時只會預留一次 creditsUsed。輪詢、下載以及重複下載相同音訊都不會再次扣款。預先扣款但失敗的工作會透過冪等退款流程退回積分。

對於批次處理，請在新增大量任務之前限制您這邊的並發並檢查設定檔。如果一項任務因積分不足而失敗，請暫停該批次的 rest，直到帳戶所有者解決餘額問題。

錯誤

狀態	意義	行動
`400`	無效的文字、語音、模型或輸出格式	修復有效負載
`401`	認證失敗	停止輪詢並刷新憑證
`402`	學分或配額不足	暫停隊列
`404`	此 API 金鑰未知任務 ID	檢查您是否儲存了相同帳號的回傳 ID
`429`	建立或輪詢請求過多	退出並保留任務 ID

非同步作業 v1

非同步作業

建立工作

回覆

找工作

找回任務 ID

計費和積分

錯誤

本頁內容