Nanobanana Py

nanobanana-py

Python MCP Server，使用 Google Gemini 模型進行 AI 圖片生成。

完整移植自 nanobanana（TypeScript 版）。

✨ 功能特色

• 🎨 文字轉圖片生成：依照描述式提示詞生成高品質圖片
• ✏️ 圖片編修：用自然語言指令修改既有圖片
• 🔧 圖片修復：修復並強化老舊或受損照片
• 🏷️ 圖示生成：生成多尺寸的 App 圖示、Favicon 與 UI 元件
• 🎯 圖樣生成：生成可無縫拼接的圖樣與背景材質
• 📖 故事序列：生成可呈現視覺故事或流程的連續圖片
• 📊 技術圖表：生成流程圖、架構圖與技術示意圖
• 🔄 自動 Fallback：主模型失敗時自動切換備用模型
• ⚡ 批次生成：支援平行生成多張圖片

📋 前置需求

1. Python 3.10+
2. API Key — 擇一：

A. Gemini Developer API（AI Studio） - NANOBANANA_GEMINI_API_KEY（建議）／ NANOBANANA_GOOGLE_API_KEY - GEMINI_API_KEY／GOOGLE_API_KEY（備援） - 取得：

B. Vertex AI Express Mode（Google Cloud，可用較新的 gemini-3.1-flash-image-preview 等模型） - NANOBANANA_VERTEX_API_KEY（建議）／ VERTEX_API_KEY（備援） - 取得：Google Cloud Console 或 AI Studio 綁定 GCP 專案的 key

> 只要設了 Vertex 專用變數，自動切 Vertex；想強制可加 NANOBANANA_PROVIDER=vertex（或 gemini）。

🚀 安裝

透過 uvx（推薦）

uvx nanobanana-py

透過 pip

pip install nanobanana-py

透過 pipx

pipx install nanobanana-py

⚙️ 設定

環境變數

# API Key（必要）
export NANOBANANA_GEMINI_API_KEY="your-api-key-here"

# 使用不同模型（預設：gemini-2.5-flash-image）
export NANOBANANA_MODEL="gemini-3-pro-image-preview"

# Fallback 模型（逗號分隔，主模型失敗時依序嘗試）
export NANOBANANA_FALLBACK_MODELS="gemini-2.5-flash-image,gemini-2.0-flash-exp-image-generation"

# API 超時秒數（預設：60）
export NANOBANANA_TIMEOUT="90"

# 自訂輸出目錄（預設：當前目錄）
export NANOBANANA_OUTPUT_DIR="/path/to/output"

# 啟用除錯日誌
export NANOBANANA_DEBUG="1"

🍌 模型選擇

此工具支援兩種模型：

🔄 自動 Fallback 機制

當主模型失敗（超時、過載或錯誤）時，會自動切換到備用模型。回應中會包含 fallback 資訊：

{
  "success": true,
  "message": "Successfully generated 1 image (使用備用模型: gemini-2.5-flash-image，原本: gemini-3-pro-image-preview)",
  "modelUsed": "gemini-2.5-flash-image",
  "usedFallback": true,
  "primaryModel": "gemini-3-pro-image-preview"
}

Claude Code 整合

在 .mcp.json 中加入：

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-py"],
      "env": {
        "NANOBANANA_GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 使用方式

🎨 generate_image - 生成圖片

從文字描述生成單張或多張圖片。

參數：

可用風格（styles）：

• photorealistic - 寫實攝影風格
• watercolor - 水彩畫風
• oil-painting - 油畫技法
• sketch - 手繪素描風
• pixel-art - 復古像素風
• anime - 動漫/漫畫風
• vintage - 復古/懷舊美學
• modern - 當代/現代風格
• abstract - 抽象藝術風
• minimalist - 乾淨、極簡設計

可用變化類型（variations）：

• lighting - 不同光線條件（戲劇化、柔和）
• angle - 不同視角（俯視、特寫）
• color-palette - 不同配色（暖色、冷色）
• composition - 不同構圖（置中、三分法）
• mood - 不同情緒氛圍（愉快、戲劇化）
• season - 不同季節（春、冬）
• time-of-day - 不同時段（日出、日落）

範例：

# 單張圖片
generate_image(prompt="一幅水彩畫：雪地森林裡的狐狸")

# 多張變體（含預覽）
generate_image(prompt="群山日落", output_count=3, preview=True)

# 指定輸出檔名
generate_image(prompt="群山日落", output_count=3, filename="sunset_mountains")

# 風格變體
generate_image(
    prompt="山景風光",
    styles=["watercolor", "oil-painting"],
    output_count=4
)

# 指定變化類型
generate_image(
    prompt="咖啡店室內",
    variations=["lighting", "mood"],
    preview=True
)

✏️ edit_image - 編修圖片

用自然語言指令修改既有圖片。

參數：

範例：

# 基本編修
edit_image(file="my_photo.png", prompt="幫人物加上太陽眼鏡")

# 指定輸出檔名
edit_image(
    file="my_photo.png",
    prompt="幫人物加上太陽眼鏡",
    filename="with_sunglasses"
)

# 編修並預覽
edit_image(
    file="portrait.jpg",
    prompt="把背景改成海灘",
    preview=True
)

🔧 restore_image - 修復圖片

修復並強化老舊或受損照片。

參數：

範例：

# 移除刮痕
restore_image(
    file="old_family_photo.jpg",
    prompt="移除刮痕並提升清晰度"
)

# 增強色彩
restore_image(
    file="damaged_photo.png",
    prompt="增強色彩並修補撕裂",
    preview=True
)

🎯 generate_icon - 生成圖示

生成多尺寸的 App 圖示、Favicon 與 UI 元件。

參數：

範例：

# 多尺寸 App 圖示
generate_icon(
    prompt="咖啡杯 logo",
    sizes=[64, 128, 256],
    type="app-icon",
    preview=True
)

# Favicon 組合
generate_icon(
    prompt="公司 logo",
    type="favicon",
    sizes=[16, 32, 64]
)

# UI 元件
generate_icon(
    prompt="設定齒輪圖示",
    type="ui-element",
    style="minimal"
)

🎨 generate_pattern - 生成圖樣

生成可無縫拼接的圖樣與背景材質。

參數：

範例：

# 無縫拼接圖樣
generate_pattern(
    prompt="幾何三角形",
    type="seamless",
    style="geometric",
    preview=True
)

# 背景材質
generate_pattern(
    prompt="木紋材質",
    type="texture",
    colors="mono"
)

# 桌布圖樣
generate_pattern(
    prompt="花卉設計",
    type="wallpaper",
    density="sparse"
)

📖 generate_story - 生成故事序列

生成連續圖片，用於說故事或呈現逐步流程。

參數：

範例：

# 視覺故事序列
generate_story(
    prompt="一顆種子長成樹",
    steps=4,
    type="process",
    preview=True
)

# 逐步教學
generate_story(
    prompt="如何煮咖啡",
    steps=6,
    type="tutorial"
)

# 時間軸視覺化
generate_story(
    prompt="智慧型手機的演進",
    steps=5,
    type="timeline"
)

📊 generate_diagram - 生成技術圖表

生成專業的技術圖表、流程圖與架構示意。

參數：

圖表類型（type）：

範例：

# 系統流程圖
generate_diagram(
    prompt="使用者登入流程",
    type="flowchart",
    style="professional",
    preview=True
)

# 系統架構圖
generate_diagram(
    prompt="微服務架構",
    type="architecture",
    complexity="detailed"
)

# 資料庫結構
generate_diagram(
    prompt="電商資料庫設計",
    type="database",
    layout="hierarchical"
)

📁 檔案管理

智慧檔名生成

圖片會依據提示詞以友善檔名儲存：

• "sunset over mountains" → sunset_over_mountains_20240101_123456_abc123.jpg
• "abstract art piece" → abstract_art_piece_20240101_123456_def456.jpg

自訂檔名

使用 filename 參數可指定輸出檔名：

• 單張：filename="mountain_view" → mountain_view.jpg
• 多張：filename="mountain_view" + output_count=3 → mountain_view_1.jpg, mountain_view_2.jpg, mountain_view_3.jpg

檔案搜尋位置

進行編修/修復時，會在以下位置搜尋輸入圖片：

1. 目前工作目錄
2. 輸出目錄（NANOBANANA_OUTPUT_DIR）
3. 使用者家目錄

輸出目錄

生成圖片會儲存到：

1. NANOBANANA_OUTPUT_DIR 環境變數指定的目錄（如有設定）
2. 目前工作目錄下的 nanobanana-output/ 子目錄（預設）

🛠️ 開發

# Clone 儲存庫
git clone https://github.com/aspect-apps/nanobanana-py.git
cd nanobanana-py

# 安裝依賴
uv sync

# 安裝開發依賴
uv sync --extra dev

# 執行測試
uv run pytest

# 格式化程式碼
uv run ruff format src/
uv run ruff check src/ --fix

🐛 疑難排解

常見問題

1. 「No API key found」

請設定 NANOBANANA_GEMINI_API_KEY 環境變數：

   export NANOBANANA_GEMINI_API_KEY="your-api-key-here"

1. 「Model timeout」或「Model overloaded」

- 稍後再試，或 - 設定 NANOBANANA_MODEL 使用其他模型 - 自動 fallback 機制會嘗試切換備用模型

1. 「Image not found」

確認輸入檔案位於支援的搜尋目錄（見「檔案搜尋位置」）

1. 圖片生成到錯誤目錄

設定 NANOBANANA_OUTPUT_DIR 環境變數指定輸出目錄：

   export NANOBANANA_OUTPUT_DIR="/path/to/output"

除錯模式

啟用除錯日誌以診斷問題：

export NANOBANANA_DEBUG="1"

📄 授權

MIT

🤝 致謝

• 原版 nanobanana by Will 保哥
• 使用 FastMCP 框架