异步图片生成
Token360 异步图片生成会创建一个持久化任务,让应用通过轮询获取结果,无需一直保持原始 HTTP 连接。
现有的 POST /v1/images/generations 接口保持同步行为不变。异步图片使用独立的 /v1/async/images/tasks 命名空间。
流程
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。
创建
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 和任务对象:
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> 关联。计费入库是异步的,因此账单记录可能比任务完成稍晚出现。
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 重试创建请求。 |