任务查询

GET /v1/tasks/:task_id

查询异步任务的执行状态和结果。响应格式与 Webhook 回调完全一致，客户端只需一套解析代码。

路径参数

参数	说明
`task_id`	提交时返回的任务 ID（`task_` 前缀）

响应字段

字段	类型	说明
`task_id`	string	任务 ID
`status`	string	`pending` / `processing` / `completed` / `failed`
`model`	string	使用的模型
`provider`	string	当前执行商家名称（`display_name`，未设置时回退到 `name`）
`elapsed_s`	integer	总耗时（秒）
`created_at`	integer	创建时间 (unix timestamp)
`completed_at`	integer	完成时间 (unix timestamp，完成/失败时)
`data`	array	生成结果（completed 时），如 `[{ "url": "..." }]`
`fail_reason`	string	失败原因（failed 时）
`total_cost`	integer	最终扣费额度（失败已退款的 attempt 不计入）
`attempt_count`	integer	尝试次数（含首次）
`attempts`	array	每次尝试的详情

attempts 子字段

字段	类型	说明
`attempt_no`	integer	尝试序号（从 1 开始）
`provider`	string	该次使用的商家（`display_name`）
`status`	string	该次状态
`fail_reason`	string	该次失败原因（如有）
`elapsed_s`	integer	该次耗时（秒，完成时）

任务状态流转

pending → processing → completed
                    ↘ failed → 自动切商家重试
                        ↘ processing (新商家) → completed

响应示例

处理中（单次）：

{
  "task_id": "task_abc123def456",
  "status": "processing",
  "model": "gpt-image-2",
  "provider": "Token8",
  "elapsed_s": 15,
  "created_at": 1714450000,
  "total_cost": 0,
  "attempt_count": 1,
  "attempts": [
    { "attempt_no": 1, "provider": "Token8", "status": "processing" }
  ]
}

已完成（单次成功）：

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "gpt-image-2",
  "provider": "Token8",
  "elapsed_s": 23,
  "created_at": 1714450000,
  "completed_at": 1714450023,
  "data": [{ "url": "https://r2.token8.pro/task_abc123def456.png" }],
  "total_cost": 5000,
  "attempt_count": 1,
  "attempts": [
    { "attempt_no": 1, "provider": "Token8", "status": "completed", "elapsed_s": 23 }
  ]
}

自动重试后成功（多次尝试）：

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "gpt-image-2",
  "provider": "Pic2API",
  "elapsed_s": 35,
  "created_at": 1714450000,
  "completed_at": 1714450035,
  "data": [{ "url": "https://r2.token8.pro/task_abc123def456.png" }],
  "total_cost": 3000,
  "attempt_count": 2,
  "attempts": [
    { "attempt_no": 1, "provider": "Token8", "status": "failed", "fail_reason": "provider_timeout", "elapsed_s": 12 },
    { "attempt_no": 2, "provider": "Pic2API", "status": "completed", "elapsed_s": 23 }
  ]
}

开启「图片/视频生成重试」后，失败自动切换商家。task_id 不变，attempts 记录完整过程。失败 attempt 的费用已自动退还，total_cost 只计成功的那次。

轮询建议

建议间隔 10-15 秒
超时上限 120 秒
推荐使用 Webhook 回调替代轮询