异步图像任务
图像生成耗时较长时,同步请求可能被代理或 CDN 超时中断(如 Cloudflare 524)。异步任务先返回任务 ID,结果通过轮询获取。
适用范围
仅 OpenAI 与 Grok 分组可用,且需要服务端开启对象存储。未开启时端点返回 404 async image tasks are not enabled。
端点
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /v1/images/generations/async | 提交生成任务 |
POST | /v1/images/edits/async | 提交编辑任务 |
GET | /v1/images/tasks/{task_id} | 查询任务 |
请求体与对应的同步接口相同(JSON 或 multipart),但不支持 stream。
提交任务
bash
curl -i https://api.thetaio.tech/v1/images/generations/async \
-H "Authorization: Bearer $THETAIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1",
"prompt": "冬夜风暴中的灯塔",
"size": "1536x1024"
}'服务端返回 202 Accepted,Location 头是轮询路径,Retry-After: 3 是建议的轮询间隔(秒):
json
{
"id": "imgtask_0123456789abcdef",
"task_id": "imgtask_0123456789abcdef",
"object": "image.generation.task",
"status": "processing",
"created_at": 1784092800,
"expires_at": 1784179200,
"poll_url": "/v1/images/tasks/imgtask_0123456789abcdef"
}查询任务
必须使用提交任务的同一个 Key 查询。其他 Key 查询会返回 404 image task not found。
bash
curl https://api.thetaio.tech/v1/images/tasks/imgtask_0123456789abcdef \
-H "Authorization: Bearer $THETAIO_API_KEY"json
{
"id": "imgtask_0123456789abcdef",
"status": "completed",
"http_status": 200,
"image_url": "https://...",
"result": {
"created": 1784092923,
"data": [{ "url": "https://..." }]
},
"completed_at": 1784092923,
"expires_at": 1784179323
}json
{
"id": "imgtask_0123456789abcdef",
"status": "failed",
"http_status": 502,
"error": { "type": "api_error", "message": "Upstream request failed" },
"completed_at": 1784092923
}成功时 result 与同步接口的响应体一致,但图片已转存:data[].url 指向存储地址,b64_json 被移除。image_url 是第一张图的地址,方便简单客户端读取。
状态与时限
| 状态 | 含义 |
|---|---|
processing | 执行中,继续轮询 |
completed | 成功,读取 result |
failed | 失败,读取 error |
- 单个任务最长执行 30 分钟。
- 任务与结果在最后一次状态更新后保留 24 小时。
- 所有响应带
Cache-Control: no-store,CDN 不会缓存processing状态。 - 只在任务成功完成后计费。
Gemini 批量图像
Gemini 图像模型的批量生成使用另一组接口 /v1/images/batches,见 Images · 批量任务。