Nano Banana 2 Lite 图像生成 - apimax · AI 大模型 API 聚合平台

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

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

鉴权#

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

text

Authorization: Bearer YOUR_API_KEY

创建任务#

POST /v1/images/async-generations

请求参数#

参数	类型	必填	默认	说明
`model`	string	是	`nano-banana-2-lite`	模型名称,填 `nano-banana-2-lite` 或 `gemini-3.1-flash-lite-image`,两种命名等价
`prompt`	string	是	—	提示词,描述要生成或编辑的图像。最多约 2000 token
`size`	string	否	`auto`	生成图像的宽高比,见下方枚举
`quality`	string	否	`1K`	清晰度档位,Lite 当前仅提供 `1K`
`image_urls`	array	否	—	参考图 URL 列表,用于图生图/图像编辑。最多 14 张,单张 < 20MB
`model_params`	object	否	—	模型扩展参数,见下方
`callback_url`	string	否	—	任务完成后的 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,Lite 当前唯一提供的档位

image_urls 参考图#

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

model_params 扩展参数#

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

请求示例#

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

json

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

指定宽高比与清晰度:

json

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

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

json

{
  "model": "nano-banana-2-lite",
  "prompt": "把这两个人物合成到同一张海报里,赛博朋克风格",
  "size": "3:4",
  "quality": "1K",
  "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-2-lite",
  "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-2-lite",
  "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-2-lite",
  "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	含义
400	`invalid_request`	缺少 prompt/model 等参数非法
400	`model_not_supported`	模型不在异步支持列表中
401	`unauthorized`	Token 无效或过期
402	`insufficient_quota`	配额不足,请充值
403	`model_access_denied`	Token 无该模型访问权限
429	`rate_limit_exceeded`	请求过于频繁
500	`internal_error`	服务器内部错误

回调(callback_url)#

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

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

鉴权#

创建任务#

请求参数#

size 宽高比#

quality 清晰度#

image_urls 参考图#

model_params 扩展参数#

请求示例#

创建任务响应#

查询任务#

status 状态#

error.code 错误码#

错误码(HTTP)#

回调(callback_url)#

下一步