查询任务

查询单个任务

POST https://www.yuntts.com/api/v1/indextts25/status

建议每 3~5 秒查询一次；任务结束后会直接返回结果，不会重复计算。

3.1 请求参数

参数	类型	必填	说明
`task_id`	String	是	创建任务时返回的 `task_id`

3.2 返回参数

参数	类型	说明
`data.task_id`	String	任务 ID
`data.status`	String	任务状态，见 3.3
`data.progress`	Integer	进度百分比：排队 30、合成中 60、完成 100
`data.audio_url`	String	音频文件地址（本站存储，可直接播放或下载）；任务未完成或保存失败时为空字符串
`data.char_count`	Integer	本次计费字符数
`data.billable_chars`	Integer / null	对账用字符数，不参与扣费
`data.points_deducted`	Number	本次预扣积分
`data.error_message`	String	失败或取消原因；成功时为空字符串
`data.created_at`	String	创建时间
`data.finished_at`	String / null	完成时间；未完成时为 `null`
`data.service_point_cost`	Integer	仅合成成功时返回：本次计费点数（对账用）

合成中的返回

{
  "code": 200,
  "message": "任务进行中",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "running",
    "progress": 60,
    "audio_url": "",
    "char_count": 36,
    "billable_chars": 30,
    "points_deducted": 0.02,
    "error_message": "",
    "created_at": "2026-10-03 10:00:00",
    "finished_at": null
  }
}

合成成功的返回

{
  "code": 200,
  "message": "合成成功",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "completed",
    "progress": 100,
    "audio_url": "https://www.yuntts.com/wp-content/uploads/my-document/audio/processed/1790984300_30859541.wav",
    "char_count": 36,
    "billable_chars": 30,
    "points_deducted": 0.02,
    "error_message": "",
    "created_at": "2026-10-03 10:00:00",
    "finished_at": "2026-10-03 10:00:20",
    "service_point_cost": 12
  }
}

3.3 任务状态

status	含义	该怎么处理
`pending`	排队中	继续轮询
`running`	合成中	继续轮询
`completed`	合成完成	用 `audio_url` 播放或下载
`failed`	合成失败	读 `error_message`，积分已自动退回
`cancelled`	已取消	积分已自动退回
`refunded`	已退款	失败或取消后的终态，积分已退回

pending ──► running ──► completed
                │
                ├──► failed ──► refunded（自动退款）
                └──► cancelled ──► refunded（自动退款）

3.4 错误码

HTTP	error	说明
400	`missing_task_id`	没传 `task_id`
404	`task_not_found`	任务不存在，或不属于当前账号
502	`service_error`	查询异常，任务状态不受影响，可继续轮询
502	`unknown_status`	出现了无法识别的任务状态，请联系管理员

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Bodyapplication/json

示例

合成成功任务进行中

{
    "code": 200,
    "message": "合成成功",
    "data": {
        "task_id": "indextts25_api_6ac0603d4cc99_1790992445",
        "status": "completed",
        "progress": 100,
        "audio_url": "https://www.yuntts.com/wp-content/uploads/my-document/audio/processed/1790992479_47284028.wav",
        "char_count": 35,
        "billable_chars": 20,
        "points_deducted": 0,
        "error_message": null,
        "created_at": "2026-10-03 09:54:05",
        "finished_at": "2026-10-03 09:54:39",
        "service_point_cost": 1
    }
}

查询单个任务#

3.1 请求参数#

3.2 返回参数#

3.3 任务状态#

3.4 错误码#