nano banana pro api image config no size parameter image 0 图示

Nano Banana Pro API 调用避坑：imageConfig 决定分辨率，不要加 size 参数

作者

很多开发者第一次调用 Nano Banana Pro API（对应 Google gemini-3-pro-image-preview 模型）时都会踩同一个坑：复用了 OpenAI / DALL-E 时代的 size: "1024x1024" 参数，结果要么生成图分辨率怎么调都不变、要么直接 400 报错、要么参数被服务端静默忽略。

这是 Nano Banana Pro API 调用最常见的"高频 bug"。正确的做法是：分辨率由 imageConfig.imageSize（清晰度 1K/2K/4K）和 imageConfig.aspectRatio（尺寸比例 1:1/16:9/…）两个参数共同决定，不要再传任何 size 字段。本文用 600 行篇幅一次讲清这件事，并给出可以直接复制运行的 curl / Python / Node.js 代码。

nano-banana-pro-api-image-config-no-size-parameter 图示

Nano Banana Pro API 调用核心要点

在动手贴代码之前，请先记住三条铁律 —— 这三条理解了，本文 90% 的内容就只是细节：

  1. 模型名称对应：Nano Banana Pro = gemini-3-pro-image-preview（也叫 Gemini 3 Pro Image），属于 Google Gemini 3 系列的图像生成/编辑模型。市面上还有人叫它 Nano Banana 2，本质是同一个东西。
  2. 协议是 Gemini 原生：不是 OpenAI Chat Completions 兼容协议。请求路径是 :generateContent，请求体顶层字段是 contents + generationConfig，没有 messages 也没有 OpenAI 风格的 size 字段。
  3. 分辨率 = imageSize × aspectRatio：imageSize 控制清晰度档位（512 / 1K / 2K / 4K），aspectRatio 控制画幅比例（1:1 / 16:9 / 9:16 / …）。两个一起决定最终输出像素。

📌 一句话总结：用 Gemini 协议调用 Nano Banana Pro，请把 OpenAI 那一套 size: "1024x1024" 习惯彻底忘掉。API易 apiyi.com 的 Nano Banana Pro 端点完整保留 Gemini 原生协议，任何在 Google 官方有效的 imageConfig 写法在 API易 也都生效。

Nano Banana Pro 关键参数速览

参数 位置 作用 取值示例
imageSize generationConfig.imageConfig 清晰度档位 "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig 画幅比例 "1:1" / "16:9" / "9:16" / "4:3" 等
responseModalities generationConfig 输出模态 ["IMAGE"]（必填）
contents[].parts[].text contents 文本 prompt 自由文本
contents[].parts[].inline_data contents 输入图(base64) 含 mime_type 和 data

⚠️ 没有列在表里的 size 字段：因为它根本不是 Gemini 协议的合法参数，不要传。

为什么不要加 size 参数？协议层原因

这是本文最核心的一节。我们用三个层面把这件事讲透。

协议层面：Gemini 和 OpenAI 是两套独立规范

OpenAI 的图像 API（DALL-E 2/3、gpt-image-1）使用顶层 size: "1024x1024" 字符串参数；而 Google Gemini 3 图像 API 设计的是嵌套的 imageConfig 对象，两套规范彼此独立。Nano Banana Pro 走的是 Gemini 原生协议，所以：

  • ❌ size: "1024x1024" —— Gemini 协议没有这个字段
  • ❌ size: "1K" —— 没有这个字段
  • ❌ n: 4 —— 没有 OpenAI 那种"一次出 N 张"的字段
  • ✅ imageConfig.imageSize: "1K" —— 正确
  • ✅ imageConfig.aspectRatio: "16:9" —— 正确

行为层面：多传 size 会发生什么？

服务端的处理通常有三种情况，没有一种是你想要的：

  1. 静默忽略：上游网关把不认识的字段当无效字段丢掉，你以为生效了，其实输出的是默认 1K 1:1。
  2. 直接报 400：严格 schema 校验的网关会因未知字段直接拒绝请求。
  3. 影响计费/路由：某些代理层会把 size 当作路由信号去匹配错误的端点版本。

工程层面：维护混乱的代码债务

很多团队把 OpenAI、Gemini、Stability 等多家 API 封装在同一个调用层，习惯性复用了一份"通用 size 字段"，看似优雅，实际是 bug 温床。建议在调用 Nano Banana Pro 这类 Gemini 原生接口时，单独走一条转换链路，把 size 显式映射成 imageConfig.imageSize + imageConfig.aspectRatio，而不是把原始 size 透传过去。

💡 建议：在用 API易 apiyi.com 调用 Nano Banana Pro 时，写一个小型的参数转换函数，把团队习惯的 "1024x1024" 这种字符串拆成 imageSize: "1K" + aspectRatio: "1:1"，从源头杜绝混传。

imageSize × aspectRatio 完整对照表

nano-banana-pro-api-image-config-no-size-parameter 图示

imageSize 档位与计费

imageSize 大致分辨率上限 输出 token 单价(参考) 推荐场景
"512" 512×512 级别 较低 最便宜 缩略图 / 草稿
"1K" 1024×1024 级别 ~1120 ≈ $0.134 默认推荐
"2K" 2048×2048 级别 ~1120 ≈ $0.134 高清海报
"4K" 4096×4096 级别 ~2000 ≈ $0.24（贵 ~80%) 印刷级

💰 成本提示：4K 比 1K/2K 贵约 80%，不要无脑全部走 4K。绝大多数 Web/App 场景 1K 已经够用，需要超清才上 4K。具体最新单价以 API易 apiyi.com 官网价目为准。

aspectRatio 完整支持列表

比例 用途
"1:1" 头像 / 社交方图
"16:9" 横屏视频封面 / 桌面壁纸
"9:16" 竖屏短视频 / 手机壁纸
"4:3" 传统照片横版
"3:4" 传统照片竖版
"3:2" / "2:3" DSLR 标准比例
"4:5" / "5:4" Instagram 单图
"21:9" 超宽屏电影感
"1:4" / "4:1" 长条 banner
"1:8" / "8:1" 极端长条特殊用途

常见组合 → 最终像素映射

imageSize aspectRatio 大致输出像素
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

注：实际像素可能因模型内部对齐规则有 ±N 像素的微调，但不影响视觉上的清晰度档位。

Nano Banana Pro API 正确调用代码

下面给出三种语言的最小可运行示例。三个示例都做同一件事：输入一张原图 + 一段 prompt，按 1K 1:1 输出一张图。

curl 版本（最直观，方便排错）

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer 你的-APIYI-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(原图base64)"
          }
        },
        {
          "text": "把这张图改成赛博朋克风格,保留人物姿态"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Python 版本（建议直接用 requests，不依赖任何 SDK）

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer 你的-APIYI-KEY",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "把这张图改成赛博朋克风格,保留人物姿态"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Node.js 版本（原生 fetch，避免 SDK 把 imageConfig 吞掉）

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer 你的-APIYI-KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "把这张图改成赛博朋克风格,保留人物姿态" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 为什么强烈建议用原生 fetch / requests：业界已知部分 SDK（包括早期 LiteLLM、Google Node SDK 的某些版本）会把 imageConfig 当作未知字段过滤掉，导致 imageSize/aspectRatio 完全无效。直接构造 JSON 请求体能 100% 避开这个坑。如果你坚持用 SDK，请先更新到最新版本并在请求拦截器里 console 输出最终 body 确认。

调用避坑清单：6 个最常见错误

nano-banana-pro-api-image-config-no-size-parameter 图示

坑 1：多传 OpenAI 风格的 size 参数

// ❌ 错误：size 不是 Gemini 协议合法字段
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ 正确：删除 size，只保留 imageConfig
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

坑 2：字段名拼写下划线 / snake_case

Gemini 3 image 接口的 imageConfig 字段名是 驼峰：imageSize、aspectRatio、responseModalities。常见错写：

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

坑 3：imageConfig 被 SDK 静默吞掉

如前所述，部分 SDK 版本会过滤未知字段。排查方法：

  1. 在 SDK 调用前后打印实际 HTTP body
  2. 用 mitmproxy / Charles 抓真实出网请求
  3. 如果发现 imageConfig 不见了，改用原生 fetch / requests

坑 4：忘记 responseModalities

// ❌ 没设 responseModalities 时,可能返回纯文本而不是图
{ "generationConfig": { "imageConfig": {...} } }

// ✅ 必须显式声明返回模态包含 IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

坑 5：429 限流没做指数退避

上游负载饱和时会返回类似：

{ "error": { "message": "当前分组上游负载已饱和,请稍后再试", "type": "upstream_error", "code": 429 } }

正确做法是指数退避重试（3s → 6s → 12s），不要立即重试，否则只会加剧拥塞：

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3s, 6s, 12s

坑 6：多张参考图传错位置

Nano Banana Pro 支持多图输入（原图 + 多张参考图）。所有图都应该作为 parts 数组里的 多个 inline_data 项，文本 prompt 放在数组最后：

// ✅ 正确：图在前,文本在后
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "原图base64" } },
  { "inline_data": { "mime_type": "image/png", "data": "参考图1base64" } },
  { "inline_data": { "mime_type": "image/png", "data": "参考图2base64" } },
  { "text": "请把原图风格迁移成参考图1的色调,构图参考参考图2" }
]

🧰 避坑总结：把上述 6 条做成你内部的"Nano Banana Pro Checklist"，每次封装新调用前过一遍，可以避免 90% 以上的低级 bug。API易 apiyi.com 的 Nano Banana Pro 端点完全沿用 Gemini 协议，所有避坑技巧通用。

用户调用流程拆解：哪一步最可能出错

nano-banana-pro-api-image-config-no-size-parameter 图示

很多读者贴出的调用日志和你给到的流程几乎一致：

前端 POST /api/generate
  → server.js 提取参数
  → 判断 modelKey.startsWith('nano-banana')
  → _generateViaGemini() 组装请求体
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → 返回 / 重试

我们逐节点标注最容易出错的环节：

环节 常见问题 建议
前端参数 习惯性传 size: "1024x1024" 拆成 imageSize + aspectRatio 两个字段透传
server.js 组装 body 误把 size 字段透传给 Gemini 在组装函数里显式 delete size
模型路由 把 nano-banana 路由到了 1.5 而不是 3 Pro 模型名严格写 gemini-3-pro-image-preview
请求发送 用了带 schema 校验的 SDK 版本 改原生 fetch，或更新 SDK 到最新版
错误处理 429 直接抛错给用户 指数退避重试 3 次
响应解析 默认按 text 取，结果是 IMAGE 正确路径 candidates[0].content.parts[0].inline_data.data

📋 一句话：你贴的流程结构是对的，只要把"参数提取"环节里那个多余的 size 字段干掉、再确认 server.js 不会把它再拼回到 generationConfig 之外，整条链路就是干净的。

FAQ 常见问题

Q1: Nano Banana Pro 和 Nano Banana 2 是同一个东西吗？
是。社区里很多人把 Gemini 3 Pro Image (gemini-3-pro-image-preview) 叫做 Nano Banana 2 / Nano Banana Pro，三种叫法指的是同一个模型。在 API易 apiyi.com 上对应的 model 名以官方文档为准。

Q2: 不传 imageConfig 会怎样？
模型会按内部默认值输出（通常是 1K + 1:1）。如果你不在意分辨率，可以省略；如果你对画幅有要求，必须显式传 imageConfig。

Q3: 我能不能既用 Gemini 协议又像 OpenAI 那样传 size？
不能可靠地这么做。Gemini 协议没有 size 字段，混传只会带来不可预期的行为。统一走 imageConfig.imageSize + imageConfig.aspectRatio 是最安全的方式。

Q4: imageSize 选 4K 是不是画质一定更好？
画质细节会更丰富，但成本也接近翻倍（~$0.24 vs $0.134），且生成时间更长。Web/App 配图用 1K 或 2K 通常已经够用。建议测试一组真实业务图，肉眼对比后再决定。

Q5: 通过 API易 apiyi.com 调用 Nano Banana Pro 和直接调 Google 官方 API 有什么差别？
API易 提供 OpenAI 风格的统一鉴权（Bearer Token）+ 国内可达入口 + 统一计费，调用协议本身完全沿用 Gemini 原生格式。这意味着你在 Google 官方文档里看到的 imageConfig / aspectRatio / responseModalities 在 API易 apiyi.com 上完全等价。

Q6: 为什么我设了 imageSize: "2K" 输出还是 1K？
最常见的 3 个原因：(1) 用了过滤未知字段的 SDK，(2) 字段名写成了 image_size，(3) generationConfig 嵌套层级写错了。先抓真实出网包确认 body 是不是符合规范，再排查服务端。

Q7: 上游 429 限流怎么办？
做指数退避重试（3s/6s/12s）。如果业务对延迟敏感，可以考虑在 API易 apiyi.com 工作区切换不同分组或申请独立配额。绝对不要写死循环立即重试，会被限流策略持续踩刹车。

Q8: 多图输入有数量上限吗？
Gemini 3 image 接口对单次请求的图片总大小有限制（通常以 MB 计，具体以官方为准）。建议参考图不超过 4-5 张，每张控制在合理大小（先 resize 再 base64），否则会触发 413 / 超时。

总结：把"分辨率两参数法"刻进肌肉记忆

如果只能记一句话带走，那就是：

Nano Banana Pro 的最终输出分辨率 = imageConfig.imageSize × imageConfig.aspectRatio，不要再传任何 OpenAI 风格的 size 字段。

完整 checklist：

  • ✅ 模型名：gemini-3-pro-image-preview
  • ✅ 端点：/v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities 必须包含 "IMAGE"
  • ✅ 多图输入放在 parts 数组里，文本 prompt 放最后
  • ✅ 429 限流走指数退避（3s/6s/12s）
  • ❌ 不要传 size: "1024x1024"
  • ❌ 不要写 image_size / aspect_ratio（snake_case 错的）
  • ❌ 不要相信会过滤未知字段的老 SDK，先抓包确认

📢 最后一句：如果你正在通过 API易 apiyi.com 接入 Nano Banana Pro，按本文给的 curl / Python / Node.js 代码模板直接复制即可，全部参数严格符合 Gemini 原生协议，复制粘贴 → 改 Key → 跑通。

作者：APIYI Team · 持续整理 AI 大模型 API 调用最佳实践 · apiyi.com

发表评论