异步图片任务查询

请求路径与认证

GET /v1/images/tasks/:task_id

根路径别名为 GET /images/tasks/:task_id。任务 ID 来自异步图片提交返回的 task_id，也可以使用提交响应中的 poll_url。若有反向代理挂载前缀，需在该路径前添加对应前缀。

必须使用提交任务时的同一个 API Key，通过 Authorization: Bearer <API_KEY> 或 x-api-key: <API_KEY> 认证。即使属于同一用户，其他 API Key 也不能查询该任务。

旧的 /v1/gpt/images/:task_id 和 /gpt/images/:task_id 已移除，不再使用 kt_... 任务 ID。

查询示例

以下为 Bash / curl 示例，将任务 ID 和 API Key 替换为实际值：

curl "https://example.com/v1/images/tasks/imgtask_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

建议每隔 3–5 秒查询一次。任务处于 pending、queued 或 processing 时，响应带有 Retry-After: 3。查询本身成功时，HTTP 状态为 200，无论任务仍在等待、执行中还是已经结束，都必须继续检查响应体中的 status。

status	含义	客户端行为
pending	任务已接收，等待进入执行队列	等待后继续轮询，不要重复提交
queued	任务已进入队列，等待执行	等待后继续轮询，不要重复提交
processing	任务执行中	等待后继续轮询
completed	任务完成，结果已可读取	停止轮询，读取图片
failed	任务失败	停止轮询，检查 error 和 http_status
expired	任务在开始执行前超过等待期限	停止轮询，检查 error 和 http_status

canceled 为预留状态，当前不提供取消任务接口。客户端可将它按终态处理，但不应依赖服务会返回此状态。

响应字段

字段	说明
id / task_id	同一个任务 ID
object	固定为 image.generation.task，图生图也使用此值
status	任务当前状态，见上表
created_at	创建时间，Unix 秒
queued_at	进入执行队列的时间，Unix 秒；尚未入队时省略
started_at	开始执行的时间，Unix 秒；尚未执行时省略
wait_expires_at	开始执行前的等待截止时间，Unix 秒；不代表执行超时或图片 URL 的有效期
completed_at	任务结束时间，Unix 秒；尚未结束时省略
expires_at	任务记录过期时间，Unix 秒；不是图片 URL 的有效期
http_status	任务结果的 HTTP 状态，不是本次查询的 HTTP 状态；尚未结束时可省略
image_url	结果中第一张图片的 URL；没有 URL 时省略
result	完成后的图片结果对象；多张图片需读取 result.data
error	失败或等待过期信息，通常含 type、message

完成响应示例

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "image_url": "https://example.com/generated-image.png",
  "result": {
    "created": 1788777000,
    "data": [{ "url": "https://example.com/generated-image.png" }]
  },
  "created_at": 1788777000,
  "queued_at": 1788777001,
  "started_at": 1788777002,
  "wait_expires_at": 1788863400,
  "completed_at": 1788777040,
  "expires_at": 1788863440
}

失败响应示例

以下表示查询成功，但任务因生成超时而结束：

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "failed",
  "http_status": 504,
  "error": {
    "type": "timeout_error",
    "message": "image generation task timed out"
  },
  "created_at": 1788777000,
  "queued_at": 1788777000,
  "started_at": 1788777000,
  "wait_expires_at": 1788863400,
  "completed_at": 1788778800,
  "expires_at": 1788865200
}

生命周期与错误处理

• 任务接收后可能经历 pending、queued、processing；轮询可能跳过持续时间较短的中间状态。pending 和 queued 都表示任务已创建，无需重新提交。
• 开始执行前最多等待 24 小时，以 wait_expires_at 为准；到期仍未开始执行的任务会变为 expired，任务结果的 http_status 为 408，但本次查询仍返回 HTTP 200。
• 执行超时为 30 分钟，从开始执行时计算，不包含排队时间。任务结束后记录保存 24 小时，结束时重新计算过期时间，以返回的 expires_at 为准。
• 任务不存在、记录已过期或不属于当前 API Key 时，查询返回 HTTP 404，错误码为 IMAGE_TASK_NOT_FOUND。
• 查询服务暂时不可用时可能返回 HTTP 503，错误码为 IMAGE_TASK_UNAVAILABLE；这属于查询失败，不等同于图片任务本身失败。可稍后重试查询，持续失败时联系服务提供方。
• 查询接口不因余额不足而拒绝读取结果，但仍需有效认证。
• 如果任务长时间没有结束，请携带任务 ID 联系服务提供方，避免重复提交。
• 完成后请及时下载图片；任务记录的 24 小时保存期不代表图片 URL 的有效期。