Skip to main content

异步图片生成

生图通常需要保活一条 HTTP 长连接等待数十秒。一旦客户端与服务之间网络中断,客户端就拿不到结果——而图片其实已经生成、费用也已产生。异步接口把”生成”与”取结果”解耦:提交后立即返回 task_id,由平台在后台代为完成生成、并把结果转存对象存储;你随后用 task_id 轮询即可。
计费只与”图是否生成成功”绑定(后扣费):提交时不扣费,只有后台真正生成成功后才扣费;生成失败不扣费。因此客户端断线、轮询超时都不会导致”扣了费却拿不到图”。

接口概览

  • 请求体与同步 /v1/images/generations 完全一致,只是 endpoint 加了 /async
  • 一套接口同时覆盖 OpenAIGemini 两类模型,按 model 自动路由。
  • 结果图片会转存到对象存储,返回稳定的签名 URL(有效期 24 小时),不受原始上游链接过期影响。

支持的模型

快速开始

只需把 <API-KEY> 换成你的 Key。下面以 Gemini nano-banana-2 为例,完整演示「提交 → 轮询 → 保存图片」。

OpenAI 模型用法

OpenAI 模型(gpt-image-2 / gpt-image-1)走相同的异步流程,只是参数遵循 OpenAI 标准:size像素、用 quality 控制质量,不使用 ratio / thinking_level

参数详解

通用参数(两类模型都支持)

Gemini 专属参数(nano-banana 系列)

Gemini 的 sizeratio 是两个维度ratio 决定形状(宽高比),size 决定清晰度档位。两者可独立组合,例如 ratio="21:9" + size="4K" 生成超宽高清图。不填时由模型用默认 1K + 1:1

OpenAI 专属参数(gpt-image 系列)

响应格式

提交响应

idtask_id,用于后续轮询。

查询响应

进行中:
完成:
generate_image 为本次生成的图片张数(等于 data 数组长度)。 失败:

任务状态

usage 字段说明(Gemini)

Gemini 生图的输出按 modality 精确拆分,便于区分计费:

最佳实践

  • 轮询间隔建议 2~5 秒,并设置总超时(如 300 秒)兜底。
  • 结果 URL 有效期 24 小时,如需长期保存请及时把图片下载到自己的存储。
  • 任务 task_id 与计费订单号对齐,排查问题时可直接用它检索。
  • 平台对上游限流 / 瞬时不可用等可重试错误会自动指数退避重试,无需业务侧重复提交。