Skip to content
使用 API

异步图像任务 ​

图像生成耗时较长时,同步请求可能被代理或 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 · 批量任务。