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-2gpt-image-2-progpt-image-2.5-flaregpt-image-2.5-sunburstgpt-image-2-vip、Doubao Seedream 系列和 Gemini 图像模型。
  • 异步任务的 image 目前只接受公网 http(s) 图片 URL,不支持 Base64 或 data: URI。
  • 成功提交后优先读取 idtask_idtaskId 作为后续查询 ID。
  • Gemini 图像模型走异步入口时,size 表示图片清晰度,按 1K / 2K 传入。
  • prompt 建议控制在 14000 个字符。
  • n 表示生成数量,常用范围为 110

方法与路径

请求示例

响应示例

认证

Body

string
required
模型名称。当前已验证可用值包括 gpt-image-2gpt-image-2-progpt-image-2.5-flaregpt-image-2.5-sunburstgpt-image-2-vipdoubao-seedream-4-0-250828doubao-seedream-4-5-251128doubao-seedream-5-0-260128gemini-3-pro-image-previewgemini-2.5-flash-image-previewgemini-3.1-flash-image-previewgemini-3.1-flash-lite-image。VIP 模型名请使用 gpt-image-2-vip,不要传 gpt-image-vip
string
required
文本提示词,用于描述想要生成的图片。建议控制在 14000 个字符。
integer
生成数量。常用范围为 110;未传时默认为 1
string
输出尺寸。gpt-image-2.5-flaregpt-image-2.5-sunburst 支持 gpt-image-2gpt-image-2-pro 的全部基础、2K4K 实际 WxH 尺寸。其它 GPT Image 模型的常见值包括 1024x10241536x10241024x15362048x20482048x11523840x21602160x38401920x10801080x1920gpt-image-2-vip 使用独立尺寸约束,常见值还包括 2304x17283264x24483504x23363808x1632。Gemini 图像模型中,size 对应 Gemini 原生 generationConfig.imageConfig.imageSize 清晰度字段,不传像素尺寸;可传 1K2Kgemini-3-pro-image-preview 支持 1K / 2Kgemini-2.5-flash-image-previewgemini-3.1-flash-image-previewgemini-3.1-flash-lite-image 会实际回落为 1K
string
图片比例。Gemini 异步生图支持该字段,传入什么比例就按什么比例生成。常见值包括 1:116:99:164:33:43:22:321:9
array<string>
可选参考图输入。数组成员当前只接受公网可访问的 http(s) 图片 URL。
string
质量等级。通用值为 lowmediumhighautogpt-image-2.5-flaregpt-image-2.5-sunburst 还支持 xhighmax。未传时默认 auto
string
返回格式。常见值为 urlb64_jsongpt-image-2-vip 不建议依赖该字段强制切换返回格式。

Response

string
异步任务 ID。后续可传入 GET /v1/images/generations/async/{taskId} 查询任务状态。
string
异步任务 ID 的兼容字段。部分响应会使用下划线命名。
string
异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
string
任务对象类型,通常为 image.generation.task
string
任务使用的图像模型,例如 gpt-image-2gpt-image-2-progpt-image-2.5-flaregpt-image-2.5-sunburstgpt-image-2-vipdoubao-seedream-4-0-250828gemini-3-pro-image-previewgemini-3.1-flash-lite-image
string
任务状态。提交后通常为 queued,轮询中可能出现 processing / in_progress
integer
任务创建时间戳。
integer
最终结果对象的生成时间戳。
string
最终结果对象的输出尺寸或清晰度,例如 1024x10241536x10243840x2160 或 Gemini 的 2K
string
最终结果对象的质量等级,例如 lowgpt-image-2.5-flaregpt-image-2.5-sunburst 也可能返回 xhighmax
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 原生请求体。
  • 提交成功后保存 idtask_idtaskId,并调用任务查询接口轮询最终结果。
  • gpt-image-2-pro 的常见高分辨率尺寸包括 2048x20483840x21602160x3840
  • gpt-image-2.5-flaregpt-image-2.5-sunburst 支持全部基础、2K4K 尺寸,具体 WxH 映射见各自生成页面。
  • gpt-image-2.5-flaregpt-image-2.5-sunburstquality 还支持 xhighmax
  • gpt-image-2-vipsize 必须满足:每条边是 16px 倍数,最长边不超过 3840px,长短边比例不超过 3:1,总像素数在 655,3608,294,400 之间。
  • Gemini 图像模型的 size 表示清晰度:gemini-3-pro-image-preview 可传 1K2Kgemini-2.5-flash-image-previewgemini-3.1-flash-image-previewgemini-3.1-flash-lite-image 会按 1K 处理。
  • Gemini 异步生图的 aspect_ratio 传入什么比例就按什么比例生成,常见值包括 1:116:99:164:33:43:22:321:9
  • 异步参考图请使用公网 http(s) URL,不能传 Base64 / data URI。

相关页面