Skip to main content
POST

图像异步生成 API

/v1/images/generations/async 用于提交图像异步生成任务。请求体采用 JSON 格式;提交成功后保存返回的任务 ID,并通过 GET /v1/images/generations/async/{taskId} 查询进度和最终结果。
  • 异步入口为 POST /v1/images/generations/async。
  • 查询入口为 GET /v1/images/generations/async/{taskId}。
  • 当前已验证可用模型包括 gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、Doubao Seedream 系列和 Gemini 图像模型。
  • 异步任务的 image 目前只接受公网 http(s) 图片 URL,不支持 Base64 或 data: URI。
  • 成功提交后优先读取 id、task_id 或 taskId 作为后续查询 ID。
  • Gemini 图像模型走异步入口时,size 表示图片清晰度,按 1K / 2K 传入。
  • prompt 建议控制在 1 到 4000 个字符。
  • n 表示生成数量,常用范围为 1 到 10。

方法与路径

请求示例

响应示例

认证

Body

string
required
模型名称。当前已验证可用值包括 gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、doubao-seedream-4-0-250828、doubao-seedream-4-5-251128、doubao-seedream-5-0-260128、gemini-3-pro-image-preview、gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview、gemini-3.1-flash-lite-image。VIP 模型名请使用 gpt-image-2-vip,不要传 gpt-image-vip。
string
required
文本提示词,用于描述想要生成的图片。建议控制在 1 到 4000 个字符。
integer
生成数量。常用范围为 1 到 10;未传时默认为 1。
string
输出尺寸。gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 支持 gpt-image-2 与 gpt-image-2-pro 的全部基础、2K 和 4K 实际 WxH 尺寸。其它 GPT Image 模型的常见值包括 1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840、1920x1080、1080x1920。gpt-image-2-vip 使用独立尺寸约束,常见值还包括 2304x1728、3264x2448、3504x2336、3808x1632。Gemini 图像模型中,size 对应 Gemini 原生 generationConfig.imageConfig.imageSize 清晰度字段,不传像素尺寸;可传 1K 或 2K。gemini-3-pro-image-preview 支持 1K / 2K;gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview 与 gemini-3.1-flash-lite-image 会实际回落为 1K。
string
图片比例。Gemini 异步生图支持该字段,传入什么比例就按什么比例生成。常见值包括 1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9。
array<string>
可选参考图输入。数组成员当前只接受公网可访问的 http(s) 图片 URL。
string
质量等级。通用值为 low、medium、high、auto;gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 还支持 xhigh 和 max。未传时默认 auto。
string
返回格式。常见值为 url、b64_json。gpt-image-2-vip 不建议依赖该字段强制切换返回格式。

Response

string
异步任务 ID。后续可传入 GET /v1/images/generations/async/{taskId} 查询任务状态。
string
异步任务 ID 的兼容字段。部分响应会使用下划线命名。
string
异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
string
任务对象类型,通常为 image.generation.task。
string
任务使用的图像模型,例如 gpt-image-2、gpt-image-2-pro、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2-vip、doubao-seedream-4-0-250828、gemini-3-pro-image-preview 或 gemini-3.1-flash-lite-image。
string
任务状态。提交后通常为 queued,轮询中可能出现 processing / in_progress。
integer
任务创建时间戳。
integer
最终结果对象的生成时间戳。
string
最终结果对象的输出尺寸或清晰度,例如 1024x1024、1536x1024、3840x2160 或 Gemini 的 2K。
string
最终结果对象的质量等级,例如 low;gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 也可能返回 xhigh 或 max。
string
最终结果对象的背景信息,例如 opaque。
string
最终结果对象的图片格式,例如 png。
object
最终结果对象里的 token 统计信息。
string
最终结果对象中 response_format = url 时返回的图片 URL。
string
最终结果对象中 response_format = b64_json 时返回的图片 Base64 数据。
string
部分上游会改写提示词并返回在这个字段里。

与同步接口的区别

使用建议

  • 如果调用方需要等待图片直接返回,优先使用同步接口 /v1/images/generations。
  • 如果任务耗时较长,或业务需要提交后异步处理,使用 /v1/images/generations/async。
  • Gemini 图像模型走异步入口时使用 OpenAI Images 兼容 JSON,不使用 /v1beta/models/{model}:generateContent 的 Gemini 原生请求体。
  • 提交成功后保存 id、task_id 或 taskId,并调用任务查询接口轮询最终结果。
  • gpt-image-2-pro 的常见高分辨率尺寸包括 2048x2048、3840x2160、2160x3840。
  • gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 支持全部基础、2K 和 4K 尺寸,具体 WxH 映射见各自生成页面。
  • gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 的 quality 还支持 xhigh 和 max。
  • gpt-image-2-vip 的 size 必须满足:每条边是 16px 倍数,最长边不超过 3840px,长短边比例不超过 3:1,总像素数在 655,360 到 8,294,400 之间。
  • Gemini 图像模型的 size 表示清晰度:gemini-3-pro-image-preview 可传 1K 或 2K;gemini-2.5-flash-image-preview、gemini-3.1-flash-image-preview 与 gemini-3.1-flash-lite-image 会按 1K 处理。
  • Gemini 异步生图的 aspect_ratio 传入什么比例就按什么比例生成,常见值包括 1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9。
  • 异步参考图请使用公网 http(s) URL,不能传 Base64 / data URI。

相关页面