Back to Details

nanobanana-mcp-image-generation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nano Banana MCP Image Generation

Nano Banana MCP 图像生成

Skill by ara.so — MCP Skills collection.
由ara.so开发的Skill——属于MCP Skills合集。

Overview

概述

Nano Banana is a production-ready MCP server that provides AI-powered image generation through Google's Gemini models. It features intelligent automatic model selection between three tiers (Flash, NB2, and Pro), 4K output, aspect ratio control, smart templates, and file management.
Key Features:
  • 🍌 Gemini 3.1 Flash Image (NB2): Default model — 4K resolution at Flash speed with Google Search grounding
  • 🏆 Gemini 3 Pro Image: Maximum reasoning depth for complex compositions
  • ⚡ Gemini 2.5 Flash Image: Legacy high-speed model for rapid prototyping
  • 🤖 Smart Auto Selection: Automatically routes to the best model based on your prompt
  • 📐 Aspect Ratio Control: 1:1, 16:9, 9:16, 21:9, and more
  • 📋 Smart Templates: Pre-built prompts for photography, design, and editing
  • 📁 File Management: Upload and reference images via Gemini Files API
Nano Banana是一款可投入生产的MCP服务器，通过Google的Gemini模型提供AI驱动的图像生成功能。它具备三大层级（Flash、NB2和Pro）模型的智能自动选择、4K输出、宽高比控制、智能模板及文件管理功能。
核心特性：
  • 🍌 Gemini 3.1 Flash Image (NB2)：默认模型——以Flash速度生成4K分辨率图像，支持Google Search grounding功能
  • 🏆 Gemini 3 Pro Image：针对复杂构图提供最大推理深度
  • ⚡ Gemini 2.5 Flash Image：用于快速原型制作的 legacy 高速模型
  • 🤖 智能自动选择：根据你的提示词自动匹配最优模型
  • 📐 宽高比控制：支持1:1、16:9、9:16、21:9等多种比例
  • 📋 智能模板：为摄影、设计和编辑场景提供预构建提示词
  • 📁 文件管理：通过Gemini Files API上传和引用图像

Installation

安装

Prerequisites

前置条件

  1. Google Gemini API Key: Get one free at https://makersuite.google.com/app/apikey
  2. Set environment variable: 
    GEMINI_API_KEY=your-api-key-here
  1. Google Gemini API密钥：可在https://makersuite.google.com/app/apikey免费获取
  2. 设置环境变量：
    GEMINI_API_KEY=your-api-key-here

MCP Client Configuration

MCP客户端配置

Claude Desktop

Claude Desktop

Add to 
~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or 
%APPDATA%\Claude\claude_desktop_config.json
(Windows):
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}
添加至
~/Library/Application Support/Claude/claude_desktop_config.json
（macOS）或
%APPDATA%\Claude\claude_desktop_config.json
（Windows）：
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Cursor

Cursor

Add to Cursor's MCP configuration:
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}
添加至Cursor的MCP配置：
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Codex (OpenAI)

Codex (OpenAI)

Add to 
~/.codex/config.toml
:
toml
[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"
添加至
~/.codex/config.toml
：
toml
[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"

Continue.dev

Continue.dev

Add to 
config.json
:
json
{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}
添加至
config.json
：
json
{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}

Vertex AI Authentication (Google Cloud)

Vertex AI认证（Google Cloud）

For production deployments on Google Cloud, use Application Default Credentials:
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}
Prerequisites for Vertex AI:
  • Enable Vertex AI API: 
    gcloud services enable aiplatform.googleapis.com
  • Grant IAM role: 
    roles/aiplatform.user
在Google Cloud上进行生产部署时，使用应用默认凭据：
json
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}
Vertex AI前置条件：
  • 启用Vertex AI API：
    gcloud services enable aiplatform.googleapis.com
  • 授予IAM角色：
    roles/aiplatform.user

Core MCP Tools

核心MCP工具

1. 
generate_image
- Generate Images from Text

1. 
generate_image
- 从文本生成图像

The primary tool for creating images from text prompts.
Parameters:
  • prompt
    (required): Text description of the image to generate
  • model_tier
    (optional): 
    "auto"
    (default), 
    "nb2"
    , 
    "pro"
    , or 
    "flash"
  • resolution
    (optional): 
    "4k"
    (3840px, default for pro/nb2) or 
    "1k"
    (1024px)
  • aspect_ratio
    (optional): 
    "1:1"
    , 
    "16:9"
    , 
    "9:16"
    , 
    "21:9"
    , 
    "4:3"
    , 
    "3:4"
    , etc.
  • n
    (optional): Number of images to generate (1-4, default 1)
  • thinking_level
    (optional): 
    "LOW"
    or 
    "HIGH"
    (Pro model only)
  • enable_grounding
    (optional): Enable Google Search grounding (boolean)
  • output_path
    (optional): Custom save path for generated images
  • negative_prompt
    (optional): Elements to avoid in the image
  • use_template
    (optional): Template ID (e.g., 
    "product_photo"
    , 
    "portrait"
    )
  • seed
    (optional): Integer for reproducible generation
Basic Usage:
python
undefined
这是根据文本提示词创建图像的核心工具。
参数：
  • prompt
    （必填）：要生成的图像的文本描述
  • model_tier
    （可选）：
    "auto"
    （默认）、
    "nb2"
    、
    "pro"
    或
    "flash"
  • resolution
    （可选）：
    "4k"
    （3840px，pro/nb2默认）或
    "1k"
    （1024px）
  • aspect_ratio
    （可选）：
    "1:1"
    、
    "16:9"
    、
    "9:16"
    、
    "21:9"
    、
    "4:3"
    、
    "3:4"
    等
  • n
    （可选）：要生成的图像数量（1-4，默认1）
  • thinking_level
    （可选）：
    "LOW"
    或
    "HIGH"
    （仅Pro模型支持）
  • enable_grounding
    （可选）：启用Google Search grounding（布尔值）
  • output_path
    （可选）：生成图像的自定义保存路径
  • negative_prompt
    （可选）：图像中需要避免的元素
  • use_template
    （可选）：模板ID（例如
    "product_photo"
    、
    "portrait"
    ）
  • seed
    （可选）：用于可复现生成的整数
基础用法：
python
undefined

Simple image generation (auto selects NB2 by default)

简单图像生成（默认自动选择NB2模型）

generate_image( prompt="A serene mountain landscape at sunset with a lake reflection" )
generate_image( prompt="日落时分宁静的山景，湖面倒映着景色" )

Generate with specific aspect ratio

指定宽高比生成图像

generate_image( prompt="Modern minimalist product photo of a coffee mug", aspect_ratio="4:3" )
generate_image( prompt="现代极简风格的咖啡杯产品照片", aspect_ratio="4:3" )

Generate multiple variations

生成多个变体

generate_image( prompt="Abstract geometric pattern in blue and gold", n=3 )

**Advanced Usage:**

```python
generate_image( prompt="蓝金配色的抽象几何图案", n=3 )

**进阶用法：**

```python

High-quality 4K generation with NB2 (default)

使用NB2模型生成高质量4K图像（默认）

generate_image( prompt="Professional product photography of a luxury watch on marble surface", model_tier="nb2", resolution="4k", aspect_ratio="16:9", enable_grounding=True )
generate_image( prompt="大理石表面上的奢华手表专业产品摄影", model_tier="nb2", resolution="4k", aspect_ratio="16:9", enable_grounding=True )

Maximum quality with Pro model

使用Pro模型生成最高质量图像

generate_image( prompt="Cinematic scene: three characters in a tense standoff at dusk, dramatic lighting", model_tier="pro", resolution="4k", thinking_level="HIGH", enable_grounding=True, negative_prompt="blurry, low quality, distorted faces" )
generate_image( prompt="电影场景：黄昏时分三个角色紧张对峙，戏剧性灯光", model_tier="pro", resolution="4k", thinking_level="HIGH", enable_grounding=True, negative_prompt="模糊、低质量、面部扭曲" )

Fast generation with Flash model

使用Flash模型快速生成图像

generate_image( prompt="Simple icon design for a mobile app", model_tier="flash", n=4 )
generate_image( prompt="移动应用的简洁图标设计", model_tier="flash", n=4 )

Custom output path

自定义输出路径

generate_image( prompt="Logo design for tech startup", output_path="/path/to/output/logo.png", aspect_ratio="1:1" )
generate_image( prompt="科技初创公司的标志设计", output_path="/path/to/output/logo.png", aspect_ratio="1:1" )

Reproducible generation with seed

使用seed实现可复现生成

generate_image( prompt="Fantasy castle in the clouds", seed=42, aspect_ratio="16:9" )
undefined
generate_image( prompt="云端中的奇幻城堡", seed=42, aspect_ratio="16:9" )
undefined

2. 
edit_image
- Edit Existing Images

2. 
edit_image
- 编辑现有图像

Edit or modify existing images with text prompts.
Parameters:
  • image_path
    (required): Path to the input image file
  • prompt
    (required): Description of the desired edit
  • model_tier
    (optional): 
    "auto"
    , 
    "nb2"
    , 
    "pro"
    , or 
    "flash"
  • mask_path
    (optional): Path to a mask image (white = edit region)
  • resolution
    (optional): 
    "4k"
    or 
    "1k"
  • output_path
    (optional): Custom save path
Usage Examples:
python
undefined
使用文本提示词编辑或修改现有图像。
参数：
  • image_path
    （必填）：输入图像文件的路径
  • prompt
    （必填）：所需编辑效果的描述
  • model_tier
    （可选）：
    "auto"
    、
    "nb2"
    、
    "pro"
    或
    "flash"
  • mask_path
    （可选）：遮罩图像的路径（白色区域为编辑区域）
  • resolution
    （可选）：
    "4k"
    或
    "1k"
  • output_path
    （可选）：自定义保存路径
用法示例：
python
undefined

Basic image editing

基础图像编辑

edit_image( image_path="/path/to/photo.jpg", prompt="Add a sunset sky in the background" )
edit_image( image_path="/path/to/photo.jpg", prompt="在背景中添加日落天空" )

Masked editing (inpainting)

遮罩编辑（图像修复）

edit_image( image_path="/path/to/portrait.jpg", prompt="Change the shirt color to blue", mask_path="/path/to/mask.png", model_tier="pro" )
edit_image( image_path="/path/to/portrait.jpg", prompt="将衬衫颜色改为蓝色", mask_path="/path/to/mask.png", model_tier="pro" )

High-quality editing with Pro model

使用Pro模型进行高质量编辑

edit_image( image_path="/path/to/landscape.jpg", prompt="Add dramatic storm clouds and rain", model_tier="pro", resolution="4k", output_path="/path/to/edited.jpg" )
undefined
edit_image( image_path="/path/to/landscape.jpg", prompt="添加戏剧性的风暴云和雨", model_tier="pro", resolution="4k", output_path="/path/to/edited.jpg" )
undefined

3. 
upload_file
- Upload Images for Reference

3. 
upload_file
- 上传图像用于参考

Upload images to Gemini Files API for use in generation or editing.
Parameters:
  • file_path
    (required): Path to the image file to upload
  • display_name
    (optional): Friendly name for the file
Usage:
python
undefined
将图像上传至Gemini Files API，以便在生成或编辑时使用。
参数：
  • file_path
    （必填）：要上传的图像文件路径
  • display_name
    （可选）：文件的友好名称
用法：
python
undefined

Upload a reference image

上传参考图像

upload_file( file_path="/path/to/reference.jpg", display_name="product_reference" )
upload_file( file_path="/path/to/reference.jpg", display_name="product_reference" )

Upload multiple references

上传多个参考图像

upload_file(file_path="/path/to/style1.jpg", display_name="style_example_1") upload_file(file_path="/path/to/style2.jpg", display_name="style_example_2")

**Then reference in generation:**

```python
generate_image(
    prompt="Create a similar product photo in the same style",
    # The uploaded files are automatically available to the model context
    model_tier="pro"
)
upload_file(file_path="/path/to/style1.jpg", display_name="style_example_1") upload_file(file_path="/path/to/style2.jpg", display_name="style_example_2")

**然后在生成时引用：**

```python
generate_image(
    prompt="创建风格相似的产品照片",
    # 上传的文件会自动在模型上下文可用
    model_tier="pro"
)

Model Selection Guide

模型选择指南

🍌 Nano Banana 2 (NB2) - Default Model

🍌 Nano Banana 2 (NB2) - 默认模型

When to use:
  • Default choice for most use cases
  • Production-ready 4K output needed
  • Text rendering in images
  • Subject consistency (multiple characters/objects)
  • Real-world accuracy (with grounding enabled)
Specs:
  • Speed: ~2-4 seconds
  • Resolution: Up to 4K (3840px)
  • Special: Google Search grounding, subject consistency, text rendering
python
generate_image(
    prompt="Instagram post with text overlay: 'Summer Sale 50% Off'",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="1:1",
    enable_grounding=True
)
适用场景：
  • 大多数场景的默认选择
  • 需要可投入生产的4K输出
  • 图像中的文字渲染
  • 主体一致性（多角色/物体）
  • 真实世界准确性（启用grounding时）
规格：
  • 速度：约2-4秒
  • 分辨率：最高4K（3840px）
  • 特色：Google Search grounding、主体一致性、文字渲染
python
generate_image(
    prompt="带文字叠加的Instagram帖子：'Summer Sale 50% Off'",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="1:1",
    enable_grounding=True
)

🏆 Pro Model - Maximum Quality

🏆 Pro模型 - 最高质量

When to use:
  • Complex narrative scenes
  • Maximum reasoning required
  • Multiple characters with intricate interactions
  • When prompt contains: "4K", "professional", "production", "cinematic"
Specs:
  • Speed: ~5-8 seconds
  • Resolution: Up to 4K (3840px)
  • Special: Advanced reasoning, configurable thinking levels
python
generate_image(
    prompt="Cinematic establishing shot: a dystopian city with three distinct districts visible, neon lights reflecting on wet streets, flying vehicles in the distance",
    model_tier="pro",
    resolution="4k",
    thinking_level="HIGH",
    enable_grounding=True
)
适用场景：
  • 复杂叙事场景
  • 需要最大推理能力
  • 具有复杂互动的多角色场景
  • 提示词中包含："4K"、"professional"、"production"、"cinematic"
规格：
  • 速度：约5-8秒
  • 分辨率：最高4K（3840px）
  • 特色：高级推理、可配置思考层级
python
generate_image(
    prompt="电影开场镜头：反乌托邦城市，可见三个不同区域，霓虹灯倒映在潮湿街道上，远处有飞行交通工具",
    model_tier="pro",
    resolution="4k",
    thinking_level="HIGH",
    enable_grounding=True
)

⚡ Flash Model - High Speed

⚡ Flash模型 - 高速

When to use:
  • High-volume generation (batches)
  • Quick drafts and iterations
  • 1024px resolution is sufficient
  • When prompt contains: "quick", "draft", "sketch"
Specs:
  • Speed: ~2-3 seconds
  • Resolution: Up to 1024px
  • Special: Fastest generation
python
generate_image(
    prompt="Quick sketch of a user interface mockup",
    model_tier="flash",
    n=4  # Generate 4 variations quickly
)
适用场景：
  • 大批量生成（批量处理）
  • 快速草稿和迭代
  • 1024px分辨率足够使用
  • 提示词中包含："quick"、"draft"、"sketch"
规格：
  • 速度：约2-3秒
  • 分辨率：最高1024px
  • 特色：最快生成速度
python
generate_image(
    prompt="用户界面原型的快速草图",
    model_tier="flash",
    n=4  # 快速生成4个变体
)

🤖 Auto Mode (Recommended)

🤖 自动模式（推荐）

Let the system intelligently select the best model:
python
undefined
让系统智能选择最优模型：
python
undefined

Auto routes to NB2 by default

默认自动路由到NB2模型

generate_image(prompt="A cat sitting on a windowsill")
generate_image(prompt="一只猫坐在窗台上")

Auto routes to Pro for quality keywords

针对质量关键词自动路由到Pro模型

generate_image(prompt="Professional 4K product photography of a watch")
generate_image(prompt="手表的专业4K产品摄影")

Auto routes to NB2 for speed keywords (NB2 is fast enough)

针对速度关键词自动路由到NB2模型（NB2速度足够快）

generate_image(prompt="Quick product thumbnail", n=3)
undefined
generate_image(prompt="快速产品缩略图", n=3)
undefined

Smart Templates

智能模板

Access pre-built prompt templates via 
use_template
parameter.
通过
use_template
参数访问预构建的提示词模板。

Available Templates

可用模板

Photography Templates:
  • product_photo
    : Clean product photography on white background
  • portrait
    : Professional portrait photography with natural lighting
  • landscape
    : Scenic landscape photography with depth
  • food
    : Appetizing food photography with natural lighting
Design Templates:
  • logo
    : Modern, minimalist logo design
  • illustration
    : Digital illustration with vibrant colors
  • abstract
    : Abstract art with geometric patterns
  • icon
    : Simple, clean icon design
Editing Templates:
  • background_replace
    : Replace image background while keeping subject
  • style_transfer
    : Apply artistic style to existing image
  • enhance
    : Enhance image quality and details
摄影模板：
  • product_photo
    ：白色背景的简洁产品摄影
  • portrait
    ：自然光线的专业人像摄影
  • landscape
    ：具有景深的风景摄影
  • food
    ：自然光线的诱人美食摄影
设计模板：
  • logo
    ：现代极简风格标志设计
  • illustration
    ：色彩鲜艳的数字插画
  • abstract
    ：几何图案抽象艺术
  • icon
    ：简洁干净的图标设计
编辑模板：
  • background_replace
    ：替换图像背景，保留主体
  • style_transfer
    ：为现有图像应用艺术风格
  • enhance
    ：提升图像质量和细节

Using Templates

使用模板

python
undefined
python
undefined

Product photography template

产品摄影模板

generate_image( prompt="wireless headphones", use_template="product_photo", aspect_ratio="1:1" )
generate_image( prompt="无线耳机", use_template="product_photo", aspect_ratio="1:1" )

Portrait template

人像模板

generate_image( prompt="female executive, confident expression", use_template="portrait", resolution="4k" )
generate_image( prompt="女性高管，自信表情", use_template="portrait", resolution="4k" )

Logo design template

标志设计模板

generate_image( prompt="tech startup focusing on AI, modern and clean", use_template="logo", aspect_ratio="1:1" )
generate_image( prompt="专注于AI的科技初创公司，现代简洁风格", use_template="logo", aspect_ratio="1:1" )

Background replacement template

背景替换模板

edit_image( image_path="/path/to/portrait.jpg", prompt="office environment with natural light", use_template="background_replace", model_tier="pro" )
undefined
edit_image( image_path="/path/to/portrait.jpg", prompt="带自然光线的办公环境", use_template="background_replace", model_tier="pro" )
undefined

Common Patterns

常见使用模式

Pattern 1: Social Media Content Generation

模式1：社交媒体内容生成

python
undefined
python
undefined

Instagram post (square)

Instagram帖子（方形）

generate_image( prompt="Motivational quote background: 'Dream Big' in elegant typography, pastel gradient", model_tier="nb2", aspect_ratio="1:1", resolution="4k" )
generate_image( prompt="励志语录背景：优雅字体的'Dream Big'，柔和渐变", model_tier="nb2", aspect_ratio="1:1", resolution="4k" )

YouTube thumbnail (16:9)

YouTube缩略图（16:9）

generate_image( prompt="Eye-catching thumbnail: person with shocked expression, bright colors, text 'You Won't Believe This!'", model_tier="nb2", aspect_ratio="16:9", enable_grounding=True )
generate_image( prompt="吸睛缩略图：表情惊讶的人物，明亮色彩，文字'You Won't Believe This!'", model_tier="nb2", aspect_ratio="16:9", enable_grounding=True )

Story/Reel (9:16)

故事/短视频（9:16）

generate_image( prompt="Vertical video background: animated gradient with floating geometric shapes", aspect_ratio="9:16", resolution="4k" )
undefined
generate_image( prompt="垂直视频背景：带浮动几何图形的动画渐变", aspect_ratio="9:16", resolution="4k" )
undefined

Pattern 2: Product Photography Workflow

模式2：产品摄影工作流

python
undefined
python
undefined

Step 1: Generate base product image

步骤1：生成基础产品图像

generate_image( prompt="Modern wireless earbuds on marble surface, studio lighting, professional product photography", model_tier="nb2", resolution="4k", aspect_ratio="4:3", output_path="/products/earbuds_base.jpg" )
generate_image( prompt="大理石表面上的现代无线耳塞，工作室灯光，专业产品摄影", model_tier="nb2", resolution="4k", aspect_ratio="4:3", output_path="/products/earbuds_base.jpg" )

Step 2: Generate variations with different angles

步骤2：生成不同角度的变体

generate_image( prompt="Same wireless earbuds, 45-degree angle, spotlight from top right", model_tier="nb2", resolution="4k", n=3 )
generate_image( prompt="同款无线耳塞，45度角，右上方聚光灯", model_tier="nb2", resolution="4k", n=3 )

Step 3: Edit to add lifestyle context

步骤3：编辑添加生活场景

edit_image( image_path="/products/earbuds_base.jpg", prompt="Add lifestyle context: gym environment in blurred background", model_tier="pro" )
undefined
generate_image( image_path="/products/earbuds_base.jpg", prompt="添加生活场景：模糊背景中的健身房环境", model_tier="pro" )
undefined

Pattern 3: Iterative Design Refinement

模式3：迭代设计优化

python
undefined
python
undefined

Start with fast iterations

从快速迭代开始

generate_image( prompt="Logo concept for coffee shop, minimalist", model_tier="flash", n=4, aspect_ratio="1:1" )
generate_image( prompt="咖啡店标志概念，极简风格", model_tier="flash", n=4, aspect_ratio="1:1" )

Refine selected concept with NB2

使用NB2优化选定的概念

generate_image( prompt="Coffee shop logo: simplified coffee cup icon with steam forming 'C' letter, earth tones", model_tier="nb2", resolution="4k", seed=12345 # Use seed from preferred flash result )
generate_image( prompt="咖啡店标志：简化的咖啡杯图标，蒸汽形成'C'字母，大地色调", model_tier="nb2", resolution="4k", seed=12345 # 使用优选Flash结果的seed )

Final high-quality version with Pro

使用Pro生成最终高质量版本

generate_image( prompt="Final coffee shop logo: refined coffee cup with elegant steam detail, warm brown and cream colors, professional branding quality", model_tier="pro", resolution="4k", aspect_ratio="1:1" )
undefined
generate_image( prompt="最终咖啡店标志：精致的咖啡杯带优雅蒸汽细节，暖棕色和奶油色，专业品牌质量", model_tier="pro", resolution="4k", aspect_ratio="1:1" )
undefined

Pattern 4: Multi-Image Campaign

模式4：多图像营销活动

python
undefined
python
undefined

Generate consistent style across multiple images

生成风格一致的多张图像

base_prompt = "e-commerce product photography, white background, soft shadows, professional lighting"
base_prompt = "电商产品摄影，白色背景，柔和阴影，专业灯光"

Image 1: Hero shot

图像1：主图

generate_image( prompt=f"{base_prompt}, luxury watch close-up, central composition", model_tier="nb2", resolution="4k", aspect_ratio="16:9", seed=100 )
generate_image( prompt=f"{base_prompt}，奢华手表特写，中心构图", model_tier="nb2", resolution="4k", aspect_ratio="16:9", seed=100 )

Image 2: Detail shot

图像2：细节图

generate_image( prompt=f"{base_prompt}, same luxury watch, focus on crown and dial details", model_tier="nb2", resolution="4k", seed=100 # Same seed for consistency )
generate_image( prompt=f"{base_prompt}，同款奢华手表，聚焦表冠和表盘细节", model_tier="nb2", resolution="4k", seed=100 # 使用相同seed保证一致性 )

Image 3: Lifestyle context

图像3：生活场景图

generate_image( prompt=f"{base_prompt}, same luxury watch on wrist, business attire visible", model_tier="pro", # Pro for complex composition resolution="4k", seed=100 )
undefined
generate_image( prompt=f"{base_prompt}，同款奢华手表戴在手腕上，可见商务着装", model_tier="pro", # 复杂构图使用Pro模型 resolution="4k", seed=100 )
undefined

Pattern 5: Image Editing Pipeline

模式5：图像编辑流水线

python
undefined
python
undefined

Upload original image

上传原始图像

upload_file( file_path="/raw/photo.jpg", display_name="original_photo" )
upload_file( file_path="/raw/photo.jpg", display_name="original_photo" )

Edit 1: Color correction

编辑1：色彩校正

edit_image( image_path="/raw/photo.jpg", prompt="Enhance colors, increase saturation slightly, professional color grading", output_path="/edited/step1_color.jpg" )
edit_image( image_path="/raw/photo.jpg", prompt="增强色彩，略微提高饱和度，专业色彩分级", output_path="/edited/step1_color.jpg" )

Edit 2: Background replacement

编辑2：背景替换

edit_image( image_path="/edited/step1_color.jpg", prompt="Replace background with modern office interior, maintain subject lighting", use_template="background_replace", model_tier="pro", output_path="/edited/step2_background.jpg" )
edit_image( image_path="/edited/step1_color.jpg", prompt="替换背景为现代办公内饰，保持主体光线", use_template="background_replace", model_tier="pro", output_path="/edited/step2_background.jpg" )

Edit 3: Final touches

编辑3：最终润色

edit_image( image_path="/edited/step2_background.jpg", prompt="Add subtle vignette, enhance sharpness, professional portrait finish", model_tier="pro", resolution="4k", output_path="/edited/final.jpg" )
undefined
edit_image( image_path="/edited/step2_background.jpg", prompt="添加微妙暗角，增强锐度，专业人像效果", model_tier="pro", resolution="4k", output_path="/edited/final.jpg" )
undefined

Aspect Ratio Quick Reference

宽高比速查表

RatioUse CaseExample
1:1
Instagram posts, profile picsSocial media content
4:3
Classic photographyProduct shots, portraits
3:4
Portrait orientationMagazine covers
16:9
Widescreen, YouTubeThumbnails, presentations
9:16
Mobile portraitPhone wallpapers, Stories
21:9
Ultra-wide cinematicMovie-style scenes
2:3
Photo print standardTraditional prints
3:2
DSLR camera standardProfessional photography
比例适用场景示例
1:1
Instagram帖子、头像社交媒体内容
4:3
经典摄影产品图、人像
3:4
竖版人像杂志封面
16:9
宽屏、YouTube缩略图、演示文稿
9:16
移动端竖屏手机壁纸、故事帖
21:9
超宽电影格式电影风格场景
2:3
照片打印标准传统打印
3:2
DSLR相机标准专业摄影

Troubleshooting

故障排除

Issue: "API Key not found"

问题："API Key not found"

Solution:
bash
undefined
解决方案：
bash
undefined

Verify environment variable is set

验证环境变量是否设置

echo $GEMINI_API_KEY
echo $GEMINI_API_KEY

For Claude Desktop, check config file has the key

对于Claude Desktop，检查配置文件中是否包含密钥

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
undefined
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
undefined

Issue: "Model not available in region"

问题："Model not available in region"

Solution:
  • NB2 and Pro models require 
    GCP_REGION=global
  • Legacy Flash model uses 
    us-central1
json
{
  "env": {
    "NANOBANANA_AUTH_METHOD": "vertex_ai",
    "GCP_PROJECT_ID": "your-project",
    "GCP_REGION": "global"
  }
}
解决方案：
  • NB2和Pro模型需要设置
    GCP_REGION=global
  • Legacy Flash模型使用
    us-central1
json
{
  "env": {
    "NANOBANANA_AUTH_METHOD": "vertex_ai",
    "GCP_PROJECT_ID": "your-project",
    "GCP_REGION": "global"
  }
}

Issue: Low-quality results

问题：生成结果质量低

Solution:
python
undefined
解决方案：
python
undefined

Use Pro model with high thinking level

使用Pro模型并设置高思考层级

generate_image( prompt="[your prompt] - photorealistic, high detail, professional quality", model_tier="pro", resolution="4k", thinking_level="HIGH", negative_prompt="blurry, low quality, distorted, artificial" )
undefined
generate_image( prompt="[你的提示词] - 照片级真实感、高细节、专业质量", model_tier="pro", resolution="4k", thinking_level="HIGH", negative_prompt="模糊、低质量、扭曲、虚假" )
undefined

Issue: Inconsistent style across generations

问题：多次生成风格不一致

Solution:
python
undefined
解决方案：
python
undefined

Use seed for reproducibility

使用seed保证可复现性

generate_image( prompt="Your prompt here", seed=42, # Same seed = similar style model_tier="nb2" )
generate_image( prompt="你的提示词", seed=42, # 相同seed=相似风格 model_tier="nb2" )

Or enable grounding for factual consistency

或启用grounding保证事实一致性

generate_image( prompt="Your prompt here", enable_grounding=True, model_tier="nb2" )
undefined
generate_image( prompt="你的提示词", enable_grounding=True, model_tier="nb2" )
undefined

Issue: File upload fails

问题：文件上传失败

Solution:
python
undefined
解决方案：
python
undefined

Check file exists and is readable

检查文件是否存在且可读

import os assert os.path.isfile("/path/to/image.jpg"), "File not found"
import os assert os.path.isfile("/path/to/image.jpg"), "文件未找到"

Supported formats: JPEG, PNG, GIF, WebP

支持格式：JPEG、PNG、GIF、WebP

Max size: 20MB per file

最大尺寸：单文件20MB

upload_file( file_path="/path/to/image.jpg", display_name="my_reference" )
undefined
upload_file( file_path="/path/to/image.jpg", display_name="my_reference" )
undefined

Issue: Generation timeout

问题：生成超时

Solution:
  • Pro model can take 5-8 seconds
  • Use NB2 for faster results (2-4 seconds)
  • Use Flash for maximum speed (2-3 seconds)
python
undefined
解决方案：
  • Pro模型可能需要5-8秒
  • 使用NB2获得更快结果（2-4秒）
  • 使用Flash获得最快速度（2-3秒）
python
undefined

If Pro times out, try NB2

如果Pro超时，尝试NB2

generate_image( prompt="Your complex prompt", model_tier="nb2", # Faster than Pro resolution="4k" # Still 4K quality )
undefined
generate_image( prompt="你的复杂提示词", model_tier="nb2", # 比Pro更快 resolution="4k" # 仍保持4K质量 )
undefined

Advanced Configuration

进阶配置

Custom Output Directory

自定义输出目录

python
import os
python
import os

Set custom output path for all generations

为所有生成设置自定义输出路径

OUTPUT_DIR = "/path/to/my/images" os.makedirs(OUTPUT_DIR, exist_ok=True)
generate_image( prompt="Landscape photo", output_path=f"{OUTPUT_DIR}/landscape_001.jpg" )
undefined
OUTPUT_DIR = "/path/to/my/images" os.makedirs(OUTPUT_DIR, exist_ok=True)
generate_image( prompt="风景照片", output_path=f"{OUTPUT_DIR}/landscape_001.jpg" )
undefined

Batch Processing with Error Handling

带错误处理的批量处理

python
prompts = [
    "Modern office interior",
    "Coastal sunset landscape",
    "Abstract geometric pattern"
]

for i, prompt in enumerate(prompts):
    try:
        generate_image(
            prompt=prompt,
            output_path=f"/batch/image_{i:03d}.jpg",
            model_tier="nb2",
            resolution="4k"
        )
    except Exception as e:
        print(f"Failed to generate image {i}: {e}")
        continue
python
prompts = [
    "现代办公内饰",
    "海岸日落风景",
    "抽象几何图案"
]

for i, prompt in enumerate(prompts):
    try:
        generate_image(
            prompt=prompt,
            output_path=f"/batch/image_{i:03d}.jpg",
            model_tier="nb2",
            resolution="4k"
        )
    except Exception as e:
        print(f"生成图像{i}失败: {e}")
        continue

Environment Variables Reference

环境变量参考

bash
undefined
bash
undefined

Required (choose one authentication method)

必填（选择一种认证方式）

GEMINI_API_KEY=your-api-key-here
GEMINI_API_KEY=your-api-key-here

OR for Vertex AI

或使用Vertex AI

NANOBANANA_AUTH_METHOD=vertex_ai GCP_PROJECT_ID=your-project-id GCP_REGION=global
NANOBANANA_AUTH_METHOD=vertex_ai GCP_PROJECT_ID=your-project-id GCP_REGION=global

Optional

可选

NANOBANANA_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR NANOBANANA_OUTPUT_DIR=/custom/output/path
undefined
NANOBANANA_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR NANOBANANA_OUTPUT_DIR=/custom/output/path
undefined

Best Practices

最佳实践

  1. Use Auto Mode by default - Let the system select the best model
  2. Specify aspect ratios - Better results than cropping after generation
  3. Enable grounding for realism - Use 
    enable_grounding=True
    for real-world accuracy
  4. Use templates - Save time with pre-optimized prompts
  5. Iterate from Flash to Pro - Start fast, refine with quality
  6. Set seeds for consistency - Reproducible results across generations
  7. Use negative prompts - Explicitly exclude unwanted elements
  8. Leverage Pro's thinking - Set 
    thinking_level="HIGH"
    for complex scenes
  9. Batch similar tasks - Generate variations with 
    n
    parameter
  10. Upload references - Use 
    upload_file
    for style/subject consistency
  1. 默认使用自动模式 - 让系统选择最优模型
  2. 指定宽高比 - 比生成后裁剪效果更好
  3. 启用grounding提升真实感 - 使用
    enable_grounding=True
    获得真实世界准确性
  4. 使用模板 - 通过预优化提示词节省时间
  5. 从Flash到Pro迭代 - 快速开始，用高质量模型优化
  6. 设置seed保证一致性 - 多次生成结果可复现
  7. 使用负面提示词 - 明确排除不需要的元素
  8. 利用Pro的思考能力 - 复杂场景设置
    thinking_level="HIGH"
  9. 批量处理相似任务 - 使用
    n
    参数生成变体
  10. 上传参考图像 - 使用
    upload_file
    保证风格/主体一致性

Resources

资源