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

异步任务

异步 TTS 把语音合成拆成创建任务和查询任务两个步骤。创建接口会校验参数、计算积分并返回任务 ID；客户端随后轮询任务详情或列表。

如果你需要在一个 HTTP 请求内立即得到音频，请使用同步 HTTP。

Endpoint

创建任务：

POST /v1/tts/tasks

列出任务：

GET /v1/tts/tasks

查询任务：

GET /v1/tts/tasks/{taskId}

完整地址示例：

https://kittaaudio.com/api/v1/tts/tasks

鉴权与请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

查询接口同样需要 Authorization。服务端会校验任务是否属于当前 token 对应账户。

创建任务请求

{
  "text": "这是一段需要异步合成的较长文本。",
  "voiceId": "clara",
  "model": "kitta-tts-v1",
  "speed": 1,
  "emotion": "calm"
}

字段	类型	必填	说明
`text`	string	是	待合成文本，最长 5000 字符
`voiceId`	string	是	音色 ID，可从 `GET /v1/voices` 获取
`model`	string	是	TTS 模型 ID，可用值以 OpenAPI schema 为准
`speed`	number	否	语速，范围 `0.5` 到 `2`，默认 `1`
`emotion`	string	否	情绪 ID，可用值以 OpenAPI schema 为准

创建任务响应

成功创建返回 202：

{
  "taskId": "tts_task_123",
  "status": "pending",
  "creditsCharged": 24
}

字段说明：

字段	说明
`taskId`	后续查询任务详情使用的 ID
`status`	初始状态，通常为 `pending` 或 `processing`
`creditsCharged`	创建任务时记录的扣费

查询任务详情

curl -X GET "https://kittaaudio.com/api/v1/tts/tasks/tts_task_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

成功响应：

{
  "id": "row_123",
  "taskId": "tts_task_123",
  "type": "tts",
  "status": "succeeded",
  "text": "这是一段需要异步合成的较长文本。",
  "voiceId": "clara",
  "model": "kitta-tts-v1",
  "audioUrl": "https://example.com/audio.mp3",
  "errorCode": null,
  "errorMessage": null,
  "creditsCharged": 24,
  "createdAt": "2026-07-01T08:00:00.000Z",
  "startedAt": "2026-07-01T08:00:02.000Z",
  "completedAt": "2026-07-01T08:00:12.000Z"
}

任务状态包括 pending、processing、succeeded 和 failed。成功任务会包含 audioUrl；失败任务会包含 errorCode 或 errorMessage。

查询任务列表

curl -X GET "https://kittaaudio.com/api/v1/tts/tasks?limit=20&offset=0&status=succeeded" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

查询参数：

参数	类型	说明
`limit`	integer	返回数量，1 到 100，默认 20
`offset`	integer	分页偏移量，默认 0
`status`	string	可选状态过滤：`pending`、`processing`、`succeeded`、`failed`

列表响应：

{
  "data": [
    {
      "taskId": "tts_task_123",
      "type": "tts",
      "status": "succeeded",
      "audioUrl": "https://example.com/audio.mp3",
      "creditsCharged": 24
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

curl 创建示例

curl -X POST "https://kittaaudio.com/api/v1/tts/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "text": "这是一段异步语音合成任务。",
    "voiceId": "clara",
    "model": "kitta-tts-v1",
    "speed": 1,
    "emotion": "calm"
  }'

错误行为

错误响应示例：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "requestId": "req_xxx"
  }
}

状态码	场景
`400`	缺少必填字段、模型不支持、字段类型错误
`401`	API Token 缺失或无效
`403`	当前账户无权访问指定资源
`402`	余额不足
`404`	查询任务不存在或不属于当前账户
`500`	任务创建、查询或供应商执行过程中发生服务端错误

建议每 3 到 5 秒查询一次任务详情，进入 succeeded 或 failed 后停止轮询。

计费与积分

异步 TTS 创建任务时返回 creditsCharged，任务详情和列表也会保留该字段。客户端可以把 taskId 和 creditsCharged 写入自己的任务表，用于和 GET /v1/usage 对账。

创建接口返回 202 表示任务已被接受，不表示音频已经生成。最终是否成功应以任务详情的 status 和 audioUrl 为准。

异步任务

On this page