异步图像任务

异步任务生命周期 ​

异步接口先返回任务标识，再由调用方轮询结果，适合可能超过客户端连接超时的图像任务。

提交任务 -> 202 processing -> 按 Retry-After 轮询 -> completed 或 failed

异步接口可能关闭；如果对象存储未启用，会返回明确的 404，且不会创建任务。提交和轮询必须使用同一把 API Key，因为任务所有权绑定到该 Key。

提交任务 ​

POST /v1/images/generations/async

curl --fail-with-body --include https://suoxie.codes/v1/images/generations/async \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL>","prompt":"A precise technical cutaway","size":"1536x1024"}'

编辑任务可以使用 POST /v1/images/edits/async，请求体与同步编辑端点一致，但不允许流式图片请求。

202 Accepted 响应 ​

提交成功返回 202 Accepted，响应头包含 Location 和 Retry-After: 3，正文包含：

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "processing",
  "created_at": 1786464000,
  "expires_at": 1786550400,
  "poll_url": "/v1/images/tasks/imgtask_example"
}

保存 task_id 或 poll_url，不要从 Location 之外自行拼接另一套域名。created_at 和 expires_at 是 Unix 时间戳，实际值以响应为准。

轮询任务 ​

GET /v1/images/tasks/<TASK_ID>

curl --fail-with-body --include https://suoxie.codes/v1/images/tasks/<TASK_ID> \
  -H "Authorization: Bearer <API_KEY>"

当状态仍为 processing 时，响应会继续提供 Retry-After: 3。等待指定秒数再查询，不要高频循环。

状态与最终响应 ​

完成响应示意：

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "image_url": "https://storage.example/image.png",
  "result": {
    "created": 1786464000,
    "data": [
      {
        "url": "https://storage.example/image.png"
      }
    ]
  },
  "created_at": 1786464000,
  "completed_at": 1786464060,
  "expires_at": 1786550400
}

失败响应会在 error 中提供类型和消息。结果会写入对象存储，不保留 b64_json。URL 和任务记录都有期限，完成后及时持久化业务需要的数据。

推荐轮询策略 ​

1. 首次等待响应头中的 Retry-After，当前通常为 3 秒。
2. 每次轮询都重新读取 Retry-After；若缺失，使用至少 3 秒的有上限退避。
3. 设置总体截止时间，并在客户端重启后从持久化的 task_id 继续。
4. completed 或 failed 后立即停止轮询。
5. 对 401、403 或 404 不原样重试。轮询返回 404 时，核对任务 ID，并使用创建任务的同一把 Key。

重要边界 ​

• 当前合约不提供取消、Webhook 或幂等保证。
• 提交请求超时且未收到 202 时，不能确定任务是否创建；先查用量和日志，避免盲目重复生成。
• 轮询不会再次产生图像生成任务，但仍应控制请求频率。
• 任务不存在、已过期或属于另一把 Key 时，都会故意返回相同的 404 Not Found，避免调用方通过任务 ID 探测其他 Key 的任务：

{
  "error": {
    "type": "IMAGE_TASK_NOT_FOUND",
    "code": "IMAGE_TASK_NOT_FOUND",
    "message": "image task not found"
  }
}

常见错误 ​

下一步 ​

将 task_id、最终状态和业务记录关联保存，但不要保存完整 Key。完成后在 Key 用量核对图像数量与费用。