创建、轮询和下载异步 TTS 任务，适合长文本、批量合成和后台处理。

文字转语音（异步）

异步 TTS 的正确流程是：创建一次任务、保存任务 ID、持续查询同一个任务，成功后下载返回的音频。不要为了恢复下载而重复创建任务。

创建任务

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

{
  "text": "这是一段异步语音合成任务。",
  "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
}

voiceId 可从 GET /api/open/v1/voices 获取。示例使用公开系统测试音色 00a1b221-6137-4b73-ad62-b0cbce134167。

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"这是一段异步语音合成任务。","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'

创建成功返回 202 Accepted。开始轮询前请保存 task.id。

{
  "task": {
    "id": "task_123",
    "taskId": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": {
      "playbackUrl": null,
      "downloadUrl": null,
      "downloadReady": false
    }
  },
  "record": {
    "id": "task_123",
    "status": "pending"
  },
  "requestId": "req_123",
  "quotaRemaining": 99993,
  "creditsUsed": 7
}

查询任务

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

建议每 3 到 5 秒查询一次，并逐步增加轮询间隔。准确的状态值如下：

状态	是否终态	说明
`pending`	否	任务已接受，等待处理
`processing`	否	正在生成音频
`success`	是	最终音频已生成
`partial_fail`	是	部分分段失败，但已有部分最终音频
`fail`	是	生成失败，没有可下载的最终音频

音频准备完成后，任务会返回 Open API 下载路由：

{
  "task": {
    "id": "task_123",
    "status": "success",
    "audioUrl": "/api/open/tts/jobs/task_123/audio",
    "delivery": {
      "playbackUrl": "/api/open/tts/jobs/task_123/audio",
      "downloadUrl": "/api/open/tts/jobs/task_123/audio?download=1",
      "downloadReady": true
    },
    "segments": []
  },
  "record": {
    "id": "task_123",
    "status": "success"
  },
  "requestId": "req_456"
}

找回任务 ID

如果创建请求已经到达服务端，但客户端没有收到 202 Accepted 响应，请先查询最近任务，不要立即重新提交相同文本：

GET /api/open/v1/speech/tts/jobs?limit=20&status=success&createdAfter=2026-07-20T00%3A00%3A00Z
Authorization: Bearer YOUR_API_KEY

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

任务按创建时间从新到旧返回。可通过 createdAt、textFingerprint、voiceId 和 engineModelId 与本地请求进行匹配。textFingerprint 是对原始 UTF-8 文本计算的 SHA-256，格式为 sha256:...。接口只返回最多 80 个字符的文本预览，不返回完整文本。

{
  "items": [
    {
      "taskId": "task_123",
      "status": "success",
      "characters": 7200,
      "textPreview": "提交文本的开头内容……",
      "textFingerprint": "sha256:0123456789abcdef...",
      "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
      "engineModelId": "fishaudio-s21pro-flash",
      "creditsUsed": 287,
      "createdAt": "2026-07-20T09:07:36.000Z",
      "audioUrl": "/api/open/tts/jobs/task_123/audio"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "hasMore": false,
    "nextPage": null
  },
  "requestId": "req_list_123"
}

支持的查询参数包括 page（默认 1）、limit（默认 20，最大 100）、status 和 ISO 8601 格式的 createdAfter。查询任务列表不会消耗 API 额度。找回 taskId 后，继续按正常流程查询状态并下载音频。

下载音频

请直接使用响应中的 task.delivery.downloadUrl，不要自行改写成网页版下载地址。该地址是需要鉴权的 Open API 路由，不是匿名 CDN 地址；下载时必须携带与创建、查询任务相同的 Bearer API Key，并允许跟随签名跳转。

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

curl -L "https://fishaudio.org/api/open/tts/jobs/task_123/audio?download=1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output speech.mp3

task.segments[].playbackUrl 中的已完成分段也需要相同的 Bearer 请求头。下载返回 401 表示 API Key 缺失或无效；返回 404 表示任务不属于当前账户，或对应音频尚不可用。

计费与重试

服务端接受任务时只预扣一次 creditsUsed。查询状态、下载音频以及重复下载同一音频都不会创建新任务，也不会再次扣费。预扣后的失败任务由服务端通过幂等退款流程退回额度。

网络失败时应保留任务 ID 并继续查询原任务。只有确认服务端没有接受创建请求时，才重新提交创建请求。批量任务请限制并发，并在继续创建前查询账户额度。

错误行为

状态码	场景
`400`	文本、音色、模型或输出格式无效
`401`	API Key 缺失或无效
`402`	API 额度不足
`404`	当前 API Key 无权访问该任务或音频
`429`	创建、轮询或下载请求过于频繁
`500`	服务端或供应商处理错误；重试前先查询原任务状态

文字转语音（异步）v1