任务查询

GET /v1/tasks/:task_id

查询异步任务的执行状态和结果。图片生成、图片编辑、视频生成和视频编辑都使用这个接口。响应格式与 Webhook 回调完全一致，客户端只需一套解析代码。

任务查询是公开只读接口，不要求 API Key。若请求里仍带有 Authorization header，服务端会忽略它。task_id 本身是短期只读访问凭证，请不要把它暴露到公开页面、第三方日志或会外泄 Referer 的 URL 中。

路径参数

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

鉴权

不要求鉴权。可以直接使用提交任务时返回的 task_id 查询：

curl "https://api.token8.pro/v1/tasks/task_abc123def456"

服务端只接受 task_ 前缀的任务 ID。错误或不存在的任务 ID 会返回 404；客户端收到 404 后应停止轮询。

如果你的 SDK 或代码复用了提交请求的 Authorization: Bearer sk-...，也可以继续发送；任务查询接口不会处理这个 header。

响应字段

字段	类型	说明
`task_id`	string	任务 ID
`status`	string	`pending` / `processing` / `completed` / `failed`
`model`	string	实际执行的模型或规格。视频生成可能显示为 `omni_flash_8s_1080p` 这类规格名
`operation`	string	`image_generation` / `image_edit` / `video_generation` / `video_edit`
`media_type`	string	`image` / `video`
`result_type`	string	业务子类型，如 `t2i`、`r2i`、`t2v`、`r2v`、`video_edit`
`file_ext`	string	结果文件扩展名，如 `png`、`jpg`、`webp`、`mp4`
`content_type`	string	结果 MIME，如 `image/png`、`video/mp4`
`duration_ms`	integer	媒体本身时长，只有上游明确返回媒体时长时才出现；不等于生成耗时
`provider`	string	当前执行商家名称（`display_name`，未设置时回退到 `name`）
`elapsed_s`	integer	当前有效 attempt 的耗时（秒）
`total_elapsed_s`	integer	从首次提交到当前状态的总耗时（秒）
`created_at`	integer	创建时间 (unix timestamp)
`completed_at`	integer	完成时间 (unix timestamp，完成/失败时)
`data`	array	生成结果（completed 时），如 `[{ "url": "..." }]`
`fail_reason`	string	失败原因（failed 时）
`message`	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	该次失败原因（如有）
`message`	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,
  "total_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",
  "operation": "image_generation",
  "media_type": "image",
  "provider": "Token8",
  "elapsed_s": 23,
  "total_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": "omni_flash_edit",
  "operation": "video_edit",
  "media_type": "video",
  "result_type": "video_edit",
  "file_ext": "mp4",
  "content_type": "video/mp4",
  "provider": "HOLO",
  "elapsed_s": 95,
  "total_elapsed_s": 95,
  "created_at": 1714450000,
  "completed_at": 1714450095,
  "data": [{ "url": "https://r2.token8.pro/abcdef12/task_abc123def456.mp4" }],
  "total_cost": 112000,
  "attempt_count": 1,
  "attempts": [
    { "attempt_no": 1, "provider": "HOLO", "status": "completed", "elapsed_s": 95 }
  ]
}

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

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "gpt-image-2",
  "provider": "Pic2API",
  "elapsed_s": 23,
  "total_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 只计成功的那次。

内容安全失败：

{
  "task_id": "task_abc123def456",
  "status": "failed",
  "model": "omni_flash_components_6s_1080p",
  "operation": "video_generation",
  "media_type": "video",
  "provider": "HOLO",
  "fail_reason": "content_policy_violation",
  "message": "提示词或参考图未通过内容安全检测，请修改后重试",
  "total_cost": 0,
  "attempt_count": 1,
  "attempts": [
    {
      "attempt_no": 1,
      "provider": "HOLO",
      "status": "failed",
      "fail_reason": "content_policy_violation",
      "message": "提示词或参考图未通过内容安全检测，请修改后重试",
      "elapsed_s": 53
    }
  ]
}

内容安全失败属于请求内容问题，不会切换商家重试；Token8 会保留上游原始错误在后台日志中，但公开任务查询只返回归一后的 fail_reason 和可展示 message。

轮询建议

首次查询建议等待 3 秒
连续处理中使用退避间隔，例如 3s → 5s → 8s → 13s → 20s
收到 completed 或 failed 后立即停止
收到 404 后立即停止，不要继续重试同一个任务
客户端等待上限建议：图片 5 分钟，视频 30 分钟
图片编辑和视频任务通常比图片生成更慢，建议优先使用 Webhook 回调
推荐使用 Webhook 回调替代轮询