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

方法与路径

请求示例

响应示例

认证

Body

model
string
required
模型名称。当前已验证可用值包括 gpt-image-2gpt-image-2-progpt-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
prompt
string
required
文本提示词,用于描述想要生成的图片。建议控制在 14000 个字符。
n
integer
生成数量。常用范围为 110;未传时默认为 1
size
string
输出尺寸。常见值包括 1024x10241536x10241024x15362048x20482048x11523840x21602160x38401920x10801080x1920gpt-image-2-vip 使用独立尺寸约束,常见值还包括 2304x17283264x24483504x23363808x1632
image
array<string>
可选参考图输入。数组成员当前只接受公网可访问的 http(s) 图片 URL。
quality
string
质量等级。常见值为 lowmediumhighauto,默认 auto
response_format
string
返回格式。常见值为 urlb64_jsongpt-image-2-vip 不建议依赖该字段强制切换返回格式。

Response

id
string
异步任务 ID。后续可传入 GET /v1/images/generations/async/{taskId} 查询任务状态。
task_id
string
异步任务 ID 的兼容字段。部分响应会使用下划线命名。
taskId
string
异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
object
string
任务对象类型,通常为 image.generation.task
model
string
任务使用的图像模型,例如 gpt-image-2gpt-image-2-progpt-image-2-vipdoubao-seedream-4-0-250828gemini-3-pro-image-previewgemini-3.1-flash-lite-image
status
string
任务状态。提交后通常为 queued,轮询中可能出现 processing / in_progress
created_at
integer
任务创建时间戳。
created
integer
最终结果对象的生成时间戳。
size
string
最终结果对象的输出尺寸,例如 1024x10241536x10243840x2160
quality
string
最终结果对象的质量等级,例如 low
background
string
最终结果对象的背景信息,例如 opaque
output_format
string
最终结果对象的图片格式,例如 png
usage
object
最终结果对象里的 token 统计信息。
data[].url
string
最终结果对象中 response_format = url 时返回的图片 URL。
data[].b64_json
string
最终结果对象中 response_format = b64_json 时返回的图片 Base64 数据。
data[].revised_prompt
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-vipsize 必须满足:每条边是 16px 倍数,最长边不超过 3840px,长短边比例不超过 3:1,总像素数在 655,3608,294,400 之间。
  • 异步参考图请使用公网 http(s) URL,不能传 Base64 / data URI。

相关页面