异步图片生成

Token360 异步图片生成会创建一个持久化任务,让应用通过轮询获取结果,无需一直保持原始 HTTP 连接。

现有的 POST /v1/images/generations 接口保持同步行为不变。异步图片使用独立的 /v1/async/images/tasks 命名空间。

流程

text
11. POST /v1/async/images/tasks                  → task id(HTTP 202)
22. GET  /v1/async/images/tasks/{task_id}        → 轮询至终态
33. POST /v1/async/images/tasks/{task_id}/cancel → 可选,尽力取消
44. GET  /v1/billing/requests/image-task:{task_id}?type=image → 对账

使用 GET /v1/async/images/tasks?limit=20 可以列出最新任务。

所有任务接口都要求在 Authorization: Bearer ... 中携带推理 API Key。接口直接返回 V1 公共 JSON 对象,并包含 Cache-Control: no-store。

创建

Shell
1curl -X POST https://api.token360.ai/v1/async/images/tasks \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -H "Idempotency-Key: image-order-20260921-0001" \
5  -d '{
6    "model": "gpt-image-2.5-flare",
7    "prompt": "日出时的水彩灯塔",
8    "size": "1024x1024",
9    "n": 1,
10    "execution": "auto"
11  }'

接口立即返回 HTTP 202 Accepted 和任务对象:

JSON
1{
2  "id": "img_task_...",
3  "object": "image_generation.task",
4  "model": "gpt-image-2.5-flare",
5  "status": "queued",
6  "execution": "auto",
7  "version": 1,
8  "created_at": "2026-09-21T12:00:00Z",
9  "updated_at": "2026-09-21T12:00:00Z"
10}

stream 必须为 false 或省略;不支持 partial_images。

执行模式

auto默认。所选路由支持供应商原生异步时使用原生异步,否则使用平台托管异步。
provider要求所选路由支持原生异步。
platform在 Token360 持久化后台任务中执行普通供应商请求。

GPT-image、Nano Banana 和其他图片模型系列共用同一组任务接口。原生异步的可用性取决于模型和路由。

幂等

每次创建任务都应携带 Idempotency-Key,最长 200 个字符。

  • 相同 key、相同请求:返回原任务和 HTTP 202,任务已完成时也一样。
  • 相同 key、不同请求:返回 HTTP 409。
  • 不传 key:每个被接受的请求都会创建新任务,并可能产生独立的供应商费用。

如果创建连接超时,请使用原 key 重试,不要为重试生成新 key。

轮询与状态

开始时建议每 2-5 秒轮询一次,随后使用带抖动的指数退避,最长约 30 秒。异步图片任务目前不支持 Webhook。

queued否已持久化,等待调度。
submitting否正在提交给选中的供应商。
in_progress否正在生成或轮询供应商任务。
cancel_requested否已请求取消;供应商仍可能完成任务。
completed是result.data 包含生成图片。
failed是生成失败,请查看 error。
cancelled是在供应商开始处理前已取消。
expired是超过服务端任务有效期。
needs_attention是提交结果不明确,系统已禁止自动重提。

出现 needs_attention 时,不要使用新的幂等 key 重试。请保留任务 ID 并联系 Token360 支持;重新向供应商提交可能造成重复图片和重复计费。

计费

完成后的用量使用 image-task:<task_id> 关联。计费入库是异步的,因此账单记录可能比任务完成稍晚出现。

Shell
1curl 'https://api.token360.ai/v1/billing/requests/image-task:img_task_...?type=image' \
2  -H "Authorization: Bearer sk-your-api-key"

错误

错误使用 V1 公共格式:{"error":{"message":"...","type":"...","code":"..."}}。

400模型或执行模式无效、不支持的流式字段、幂等 key 无效,或 limit 不是整数。
401未提供有效的推理 API Key。
404任务不存在或不属于当前调用方。
409同一幂等 key 已用于不同请求。
413持久化任务请求超过服务端配置的大小限制。
500服务端异常。仅可使用原幂等 key 重试创建请求。

相关 API 参考

此页面对您有帮助吗?
异步图片生成 · Token360