跳转到主要内容
图片异步接口适合长耗时、按张计费的图片生成场景。它不是 OpenAI 同步图片接口的简单别名，而是平台任务制接口：创建任务后立即返回任务 ID，平台在后台处理生成和结果转存，再按成功返回的图片数结算。
OpenAI 兼容图片接口仍是 /v1/images/generations；图片异步接口是 /v2/images/generations。两者在模型、endpoint、计费和返回结构上是隔离的。

​
适用场景

场景推荐接口
需要 OpenAI 兼容同步响应/v1/images/generations
需要按张计费、任务状态、后台转存结果图/v2/images/generations
需要一次生成多张图片当前创建多个异步任务；不要传 n

​
创建任务

curl -X POST "https://xxx.wengaocloud.com/v2/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "prompt": "一张极简风格的云端工作站海报，蓝白配色，科技感",
    "size": "1:1"
  }'

​
请求字段

字段类型必填说明
modelstring是支持 images_generations_async endpoint 的图片异步模型，例如 gpt-image-2-async
promptstring是图片生成提示词
sizestring否输出比例或尺寸口径，以模型能力为准；常用比例类值例如 1:1、16:9
urlsstring[]否参考图 URL 列表。当前默认最多 8 张，超出会返回 400
当前实现会拒绝 n 字段，返回 invalid_request_error。如果业务需要多张图片，请创建多个任务；不要把多个任务塞进一个请求。

​
创建响应

{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "queued",
  "created_at": 1779860000
}
status=queued 表示任务已经创建并完成冻结，后续由平台异步处理生成和结果转存。

​
查询任务

curl "https://xxx.wengaocloud.com/v2/images/generations/imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3" \
  -H "Authorization: Bearer $AI_API_KEY"

​
处理中响应

{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "running",
  "created_at": 1779860000,
  "completed_at": null
}

​
成功响应

{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "succeeded",
  "created_at": 1779860000,
  "completed_at": 1779860032,
  "result": {
    "images": [
      {
        "url": "https://cdn.wengaocloud.com/images/ai/example.png"
      }
    ]
  }
}
返回给用户的是问高云侧结果图 URL。结果存储、URL 有效期和清理策略以后端配置为准。

​
失败响应

{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "failed",
  "created_at": 1779860000,
  "completed_at": 1779860032,
  "error": {
    "code": "image_generation_failed",
    "message": "图片生成失败"
  }
}

​
状态说明

状态含义
queued本地任务已创建，等待 worker 处理
running平台正在处理图片生成任务
succeeded已成功转存结果图并完成结算
failed生成失败、结果缺失、转存失败或其他异常，平台会按结算策略退款或复核
cancelled任务已取消，当前阶段通常不由用户主动触发

​
计费与安全

  • 创建任务前会检查模型可见性、API Key 白名单、模型能力、价格配置和余额。
  • 创建成功后会冻结预计费用；成功后按实际成功存储并返回的图片数结算。
  • 任务查询按 task_id + 用户 + 域名 + API Key 做归属校验，不能查询其他 Key 创建的任务。
  • 结果图 URL 视为敏感数据，不应该出现在普通日志、账单导出或公开错误信息中。
如果你想做前端轮询，建议 2-5 秒查一次任务状态；不要高频刷新。