nanobanana

Nano Banana

一個單一的 Python 進入點，用於 Gemini 原生的 Nano Banana 圖片生成與編輯，支援模型別名、嚴格的選項驗證、批次執行及自訂端點。

工作流程

1. 開啟 references/config.md 選擇環境變數與覆蓋順序。
2. 開啟 references/models-and-api.md 挑選合適的 Nano Banana 層級，並檢查模型特定的限制。
3. 除非你需要最快的低成本預設 (nanobanana) 或最高保真度的推理模型 (nanobanana-pro)，否則優先使用 gemini-3.1-flash-image-preview (nanobanana-2)。
4. 執行 scripts/nanobanana.py generate 進行單次請求，或 scripts/nanobanana.py batch 進行重複變體。
5. 當主要風險在於請求內容結構、端點或模型特定選項支援時，先加上 --dry-run。
6. 當你需要自訂 Gemini 相容閘道時，傳入 --base-url 或 GEMINI_BASE_URL。
7. 在 generate 指令中加上 --save-response <path>，以便取得原始 JSON 回應進行除錯。

指令

單次文字轉圖片請求：

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "開發者工具的復古未來風格產品主圖插畫" `
  --output .\out\hero.png `
  --model nanobanana-2 `
  --ratio 16:9 `
  --size 2K

使用兩個本地參考編輯現有圖片：

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "將這些參考轉換為乾淨的發布海報，並加上清晰標題文字" `
  --input-image .\refs\subject.png `
  --input-image .\refs\background.png `
  --output .\out\poster.png `
  --model nanobanana-pro `
  --ratio 4:5 `
  --size 2K

使用自訂 Gemini 相容閘道：

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "大膽的吉祥物貼紙包" `
  --output .\out\stickers.png `
  --base-url http://your-gateway.example.com/v1beta `
  --auth-mode bearer

批次生成五個變體：

python .\skills\nanobanana\scripts\nanobanana.py batch `
  --prompt "PDF 工作流程產品的極簡應用程式圖示" `
  --count 5 `
  --dir .\out\icons `
  --prefix icon `
  --model nanobanana `
  --ratio 1:1

檢查最終請求但不實際發送：

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "AI 代理在工作中的編輯插畫" `
  --model nanobanana-2 `
  --output .\out\agents.png `
  --dry-run

規則

• --model 接受別名 nanobanana、nanobanana-2 和 nanobanana-pro，或完整的 Gemini 模型 ID。
• nanobanana 解析為 gemini-2.5-flash-image，nanobanana-2 解析為 gemini-3.1-flash-image-preview，nanobanana-pro 解析為 gemini-3-pro-image-preview。
• image_size 僅在 Gemini 3 圖片模型上有效；nanobanana 會拒絕 --size。
• 512 解析度僅在 nanobanana-2 上有效。
• 處理環境變數會覆蓋 .env；CLI 旗標會覆蓋兩者。
• 絕不輸出機密資訊。
• generate 接受重複的 --input-image 路徑，用於圖片編輯或多參考生成。
• --base-url 應指向 Gemini API 根路徑，例如 https://generativelanguage.googleapis.com/v1beta，而不是直接指向 /models/...。
• --auth-mode auto 對官方 Google 端點使用 x-goog-api-key，對自訂端點則同時發送 Authorization: Bearer 和 x-goog-api-key，以最大化閘道相容性。

資源

• 腳本：scripts/nanobanana.py
• 設定參考：references/config.md
• 模型與 API 參考：references/models-and-api.md