apimaxDocs
文档定价控制台
API 参考接入指南用户指南更新日志

图像系列

POSTNano Banana 2 图像生成POSTNano Banana Pro 图像生成POSTNano Banana 2 Lite 图像生成

任务管理

错误码参考查询任务状态GET

账户管理

查询额度使用情况GET

文档 / 图像系列 / Nano Banana / 异步

异步POSTImage GenerationNano-BananaGeminiAsyncgemini-3-pro-image-preview

Nano Banana Pro 图像生成

Google Nano Banana Pro(Gemini)异步图像生成,擅长多图融合、真人参考与文字渲染,支持思考推理级别。

POST/v1/images/async-generations
试一试
Bearer API KeyJSON服务端调用

Nano Banana Pro(nano-banana-pro)是基于 Google Gemini 的新一代图像生成模型,擅长文生图、图生图与图像编辑,在多图融合、真人参考与文字渲染上表现出色。本接口兼容 OpenAI Images API 格式,采用异步任务模式:提交后返回任务 ID,再轮询查询结果。

- 异步模式走独立端点 POST /v1/images/async-generations,提交后返回 task_id,使用查询任务接口获取结果。 - model 传 nano-banana-pro 或 gemini-3-pro-image-preview 均可,两种命名等价。 - 生成的图像链接为预签名 URL,有效期约 24 小时,请及时保存。 - 该模型单次仅生成 1 张图(n 固定为 1)。

鉴权#

所有接口均需通过 Bearer Token 认证。请在 API Key 管理页面 创建你的 Key,并在请求头中添加:

text
Authorization: Bearer YOUR_API_KEY

创建任务#

POST /v1/images/async-generations

请求参数#

参数类型必填默认说明
modelstring是nano-banana-pro模型名称,填 nano-banana-pro 或 gemini-3-pro-image-preview,两种命名等价
promptstring是—提示词,描述要生成或编辑的图像。最多约 2000 token
sizestring否auto生成图像的宽高比,见下方枚举
qualitystring否2K清晰度档位 1K/2K/4K,不同档位价格不同
image_urlsarray否—参考图 URL 列表,用于图生图/图像编辑。最多 14 张,单张 < 20MB
model_paramsobject否—模型扩展参数,见下方
callback_urlstring否—任务完成后的 HTTPS 回调地址

size 宽高比#

默认 auto(由模型自动决定)。支持以下取值:

auto、1:1、1:4、4:1、1:8、8:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9

quality 清晰度#

取值说明
1K约 1MP,速度最快,成本最低
2K约 4MP(默认),质量与成本均衡
4K约 8MP,细节最丰富,成本最高

image_urls 参考图#

  • 单次请求最多输入 14 张图像,单张 < 20MB
  • 支持格式:.jpeg、.jpg、.png、.webp
  • 图像 URL 需服务器可直接访问,或访问时直接下载(通常以 .png、.jpg 等扩展名结尾)
  • 其中最多可传入 4 张真人图像

model_params 扩展参数#

字段类型默认说明
thinking_levelstringauto思考推理级别:auto 自动 / min 最少推理最快 / high 深度推理最佳质量

请求示例#

请求体与同步 OpenAI Images API 同构。最简文生图:

json
{
  "model": "nano-banana-pro",
  "prompt": "一只猫在草地上玩耍"
}

指定宽高比与清晰度:

json
{
  "model": "nano-banana-pro",
  "prompt": "黄昏时分未来都市天际线的电影级广角镜头",
  "size": "16:9",
  "quality": "4K"
}

图生图 / 多图融合(传入参考图)+ 深度推理:

json
{
  "model": "nano-banana-pro",
  "prompt": "把这两个人物合成到同一张海报里,赛博朋克风格",
  "size": "3:4",
  "quality": "2K",
  "image_urls": [
    "https://example.com/person1.png",
    "https://example.com/person2.png"
  ],
  "model_params": {
    "thinking_level": "high"
  },
  "callback_url": "https://your-domain.com/webhook/image-done"
}

创建任务响应#

提交成功后立即返回任务信息(HTTP 200):

json
{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "queued",
  "progress": 0,
  "created": 1757165031,
  "model": "nano-banana-pro",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 45
  }
}

id 即任务标识(task_ 前缀),用于后续查询。

查询任务#

GET /v1/tasks/{id}

bash
curl 'https://api.apimax.ai/v1/tasks/task_V1StGXR8_Z5jdHi6B' \
  --header 'Authorization: Bearer <token>'

建议每 2~5 秒轮询一次,直到 status 变为 completed 或 failed。

已完成(`completed`):

json
{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "completed",
  "progress": 100,
  "created": 1757165031,
  "completed_at": 1757165076,
  "model": "nano-banana-pro",
  "data": [
    {
      "url": "https://cdn.example.com/img/.../0.png?X-Amz-Signature=...",
      "url_expires_at": 1757168676
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1290,
    "total_tokens": 1308
  }
}

预签名 URL 每次查询都会重新签发,因此轮询即可"刷新"过期链接。

失败(`failed`):

json
{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "failed",
  "failed_at": 1757165076,
  "model": "nano-banana-pro",
  "error": {
    "code": "upstream_error",
    "message": "gemini blocked: SAFETY"
  }
}

status 状态#

状态含义
queued已入队,等待执行
in_progress正在生成
completed生成完成,data 中为图像链接
failed生成失败,见 error

error.code 错误码#

Code含义
upstream_error上游返回 4xx(内容安全拦截 / 提示词非法)
upstream_unavailable上游多次重试后仍 5xx
storage_error结果上传云存储失败
internal_error网关内部异常

任务失败会自动退还预扣的配额。

错误码(HTTP)#

状态码code含义
400invalid_request缺少 prompt/model 等参数非法
400model_not_supported模型不在异步支持列表中
401unauthorizedToken 无效或过期
402insufficient_quota配额不足,请充值
403model_access_deniedToken 无该模型访问权限
429rate_limit_exceeded请求过于频繁
500internal_error服务器内部错误

回调(callback_url)#

设置 callback_url 后,任务完成 / 失败 / 取消时网关会主动 POST 回调,回调体格式与查询任务接口一致。

  • 仅支持 HTTPS,禁止回调到内网 IP,URL ≤ 2048 字符
  • 超时 10 秒,失败最多重试 3 次(分别在 1s / 2s / 4s 后)
  • 回调返回 2xx 视为成功,其他状态码触发重试

下一步

全部文档
GPT Image 2 图像生成/v1/images/async-generationsNano Banana 2 图像生成Google Nano Banana 2(Gemini)异步图像生成,擅长多图融合、真人参考与文字渲染,支持思考推理级别。Nano Banana 2 Lite 图像生成Google Nano Banana 2 Lite(Gemini)异步图像生成,轻量快速、成本更低,擅长多图融合与图像编辑。Nano Banana 同步图像生成Gemini 图像模型(nano-banana 系列)支持 OpenAI 兼容同步生图与 multipart 图像编辑,默认返回 base64,并兼容 OpenAI SDK。GPT Image Web 图像生成GPT Image Web 渠道异步图像生成，使用模型名 gpt-image-web，支持基础文生图、图生图与尺寸参数。
本页导航
概览鉴权创建任务请求参数size 宽高比quality 清晰度imageurls 参考图modelparams 扩展参数请求示例创建任务响应查询任务status 状态error.code 错误码错误码(HTTP)回调(callbackurl)下一步
API

POST /v1/images/async-generations