图像异步生成
图像异步生成 API
使用 POST /v1/images/generations/async 提交图像异步生成任务,并通过任务查询接口获取最终结果。
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-vip、Doubao Seedream 系列和 Gemini 图像模型。 - 异步任务的
image目前只接受公网http(s)图片 URL,不支持 Base64 或data:URI。 - 成功提交后优先读取
id、task_id或taskId作为后续查询 ID。 prompt建议控制在1到4000个字符。n表示生成数量,常用范围为1到10。
方法与路径
请求示例
响应示例
认证
Body
模型名称。当前已验证可用值包括
gpt-image-2、gpt-image-2-pro、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。文本提示词,用于描述想要生成的图片。建议控制在
1 到 4000 个字符。生成数量。常用范围为
1 到 10;未传时默认为 1。输出尺寸。常见值包括
1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840、1920x1080、1080x1920。gpt-image-2-vip 使用独立尺寸约束,常见值还包括 2304x1728、3264x2448、3504x2336、3808x1632。可选参考图输入。数组成员当前只接受公网可访问的
http(s) 图片 URL。质量等级。常见值为
low、medium、high、auto,默认 auto。返回格式。常见值为
url、b64_json。gpt-image-2-vip 不建议依赖该字段强制切换返回格式。Response
异步任务 ID。后续可传入
GET /v1/images/generations/async/{taskId} 查询任务状态。异步任务 ID 的兼容字段。部分响应会使用下划线命名。
异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
任务对象类型,通常为
image.generation.task。任务使用的图像模型,例如
gpt-image-2、gpt-image-2-pro、gpt-image-2-vip、doubao-seedream-4-0-250828、gemini-3-pro-image-preview 或 gemini-3.1-flash-lite-image。任务状态。提交后通常为
queued,轮询中可能出现 processing / in_progress。任务创建时间戳。
最终结果对象的生成时间戳。
最终结果对象的输出尺寸,例如
1024x1024、1536x1024 或 3840x2160。最终结果对象的质量等级,例如
low。最终结果对象的背景信息,例如
opaque。最终结果对象的图片格式,例如
png。最终结果对象里的 token 统计信息。
最终结果对象中
response_format = url 时返回的图片 URL。最终结果对象中
response_format = b64_json 时返回的图片 Base64 数据。部分上游会改写提示词并返回在这个字段里。
与同步接口的区别
使用建议
- 如果调用方需要等待图片直接返回,优先使用同步接口
/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-vip的size必须满足:每条边是16px倍数,最长边不超过3840px,长短边比例不超过3:1,总像素数在655,360到8,294,400之间。- 异步参考图请使用公网
http(s)URL,不能传 Base64 / data URI。