nano banana pro api image config no size parameter zh hant 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-zh-hant 图示

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-zh-hant 图示

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-zh-hant 图示

坑 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-zh-hant 图示

很多讀者貼出的調用日誌和你給到的流程幾乎一致：

前端 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

發佈留言