Nano banana 2.1 图像生成

模型选择

模型 ID	计费方式	单次出图张数	参考图大小
`gemini-nano-banana-2.1`	按实际 token 用量	1–4 张	单张不超过 20MB
`gemini-nano-banana-2.1-ext`	按分辨率档位、按张计费	仅 1 张	单张不超过 20MB，合计不超过 50MB

两个模型的出图尺寸和画质一致。需要一次生成多张图片请选择官方版；需要按张估算费用可选择 Ext 版。实际价格以模型定价为准。

信息

本接口为异步接口。提交成功后返回 task_id，请通过任务查询获取状态和图片。建议每 3–5 秒轮询一次，整体等待超时设置为至少 3 分钟。

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.openveer.com/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gemini-nano-banana-2.1",
        "prompt": "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
        "size": "16:9",
        "resolution": "2K",
        "n": 1
    }
)
print(response.json())

const response = await fetch("https://api.openveer.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-nano-banana-2.1",
    prompt: "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
    size: "16:9",
    resolution: "2K",
    n: 1
  })
});
console.log(await response.json());

响应示例

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

请求头

Authorization string

Bearer 认证，格式为 Bearer <token>，其中 <token> 为你的 OpenVeer API Key。

请求参数

model string

模型 ID：gemini-nano-banana-2.1 或 gemini-nano-banana-2.1-ext。

prompt string

图像生成或编辑的文本描述，支持中文和英文。

size string

输出宽高比。支持 1:4、4:1、1:8、8:1、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9，兼容 16x9 形式的写法。

不传或传 auto 时由模型决定；图生图会跟随参考图比例。

官方版在 1K、2K、4K 下均支持上述 14 种比例。Ext 版仅在 1K 下支持 1:4、4:1、1:8、8:1；2K、4K 不支持这四种比例，仅支持其余 10 种比例。

resolution string

输出分辨率档位：1K、2K 或 4K，兼容小写，同时影响计费。

不支持 0.5K 或 512，提交时会返回 HTTP 400。其他无法识别的值（如 3K）会按 1K 生成和计费，建议只使用上述支持的值。

n integer

生成图片数量：官方版支持 1–4 张，Ext 版仅支持 1 张。

大于 4 时提交直接返回 HTTP 400；Ext 版传入 2–4 时任务会在执行阶段失败并全额退款。需要多张时请分别提交 Ext 任务，或使用官方版。

image_urls string[]

参考图列表。不传为文生图，传入则为图生图或图像编辑。每项支持：

公网可访问的 HTTP(S) 图片 URL。
Base64 Data URL，例如 data:image/png;base64,...。

建议使用 PNG、JPEG 或 WEBP。官方版单张不超过 20MB；Ext 版单张不超过 20MB，所有参考图合计不超过 50MB。

平台未设置固定的参考图张数上限，但不代表可以无限上传：超出模型支持范围时任务可能失败并退款，参考图越多通常耗时越长。

official_fallback boolean

仅适用于 gemini-nano-banana-2.1-ext。开启后，Ext 版失败时尝试使用官方版完成任务。

实际使用官方版完成时，改为按官方版的实际 token 用量计费，不再按 Ext 版的按张价格计费。

webhook string

任务结束后的回调地址，详见任务回调。

输出尺寸参考

宽高比	1K	2K	4K
1:1	1024×1024	2048×2048	4096×4096
2:3	848×1264	1696×2528	3392×5056
3:2	1264×848	2528×1696	5056×3392
3:4	896×1200	1792×2400	3584×4800
4:3	1200×896	2400×1792	4800×3584
4:5	928×1152	1856×2304	3712×4608
5:4	1152×928	2304×1856	4608×3712
9:16	768×1376	1536×2752	3072×5504
16:9	1376×768	2752×1536	5504×3072
21:9	1584×672	3168×1344	6336×2688

上述尺寸包含实测值及系列尺寸参考值，并非所有组合均已实测，实际像素尺寸以返回图片为准。

编辑参考图

{
  "model": "gemini-nano-banana-2.1-ext",
  "prompt": "给画面里的猫戴上一顶红色毛线帽，其余保持不变",
  "image_urls": ["https://example.com/cat.jpg"],
  "resolution": "1K"
}

请将示例 URL 替换为实际可访问的图片地址。不传 size 时输出跟随参考图比例。

批量生成（仅官方版）

{
  "model": "gemini-nano-banana-2.1",
  "prompt": "赛博朋克风格的城市夜景，霓虹灯，雨后街道",
  "size": "16:9",
  "resolution": "2K",
  "n": 4
}

提交响应

code integer

响应状态码，成功为 200。

data array

任务提交结果。status 为 submitted，task_id 用于查询任务状态和结果，不是最终图片地址。

查询任务结果

curl --request GET \
  --url https://api.openveer.com/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'

成功响应示例（图片 URL 为占位示例）：

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"],
          "expires_at": 1791417625
        }
      ]
    }
  }
}

任务状态	含义
`pending`	排队中
`processing`	生成中
`completed`	成功，从 `data.result.images[0].url` 读取图片链接数组
`failed`	失败，从 `data.error.message` 读取原因；全额退款，`data.cost` 为 0

所有成品图片链接均在 data.result.images[0].url 数组中，生成 4 张时此数组包含 4 个链接。平台仅返回成品图，n=1 对应 1 张成品图。

链接有效期为任务完成后 24 小时，以 expires_at 为准，请及时下载转存。输出为 PNG 或 JPEG，以实际文件内容为准。查询结果中的 data.cost 为最终扣费金额（美元）。

计费说明

官方版：按实际输入和输出 token 用量计费，提示词和参考图计入输入用量。提交时按分辨率档位和 n 预扣，完成后按实际用量多退少补。
Ext 版：按分辨率档位单价 × 实际出图张数计费，宽高比不影响档位。开启 official_fallback 且实际使用官方版时，改按官方版 token 计费。
具体单价以模型定价为准。提交阶段直接拒绝的请求不创建任务、不扣费；任务失败全额退款。

常见错误

情况	处理方式
HTTP 400	检查是否传入 `0.5K` / `512`、`n` 大于 4 或参考图超过单张大小上限
HTTP 401	检查 API Key
HTTP 402	检查余额是否足以覆盖预扣费用
HTTP 429	触发限流，请退避后重试
任务失败：不支持的宽高比	检查 `size` 是否适用于当前模型和分辨率，或使用 `auto`
任务失败：Ext 版请求多张	将 `n` 改为 1，或使用官方版
任务失败：内容安全拦截	修改提示词或参考图后重试
任务失败：参考图下载失败	确认图片 URL 可以从公网访问

警告

Nano banana 2.1 与 Gemini 3.1 Flash Image 是不同模型，模型名不能作为别名互换。从后者迁移时，请移除不支持的 0.5K 分辨率。