nano-banana-pro

Nano Banana Pro 图像生成与编辑

使用 Google 的 Gemini 3 Pro 模型生成和编辑图像，并支持高级透明度处理。

前提条件

1. 依赖项：

   pip install google-genai Pillow numpy python-dotenv
   

2. API 密钥：脚本会自动从 .env 加载。仅当脚本因「No API key found」而失败时，才询问用户。

CLI 用法（必需）

始终使用 CLI 脚本。不要编写 Python 代码或创建 .py 文件。

直接运行 scripts/generate.py：

# Basic generation
python scripts/generate.py "a cute banana sticker" -o banana.png

# With transparency (for game assets, stickers, icons)
python scripts/generate.py "pixel art sword" -o sword.png --transparent

# Custom size and aspect ratio
python scripts/generate.py "game logo" -o logo.png --size 4K --ratio 16:9

选项：

• -o, --output - 输出文件名（默认：output.png）
• --transparent - 使用差异抠图提取真实 Alpha 通道
• --size - 1K、2K 或 4K（默认：2K）
• --ratio - 宽高比：1:1、16:9、9:16 等（默认：1:1）
• --model - 覆盖模型（默认：gemini-3-pro-image-preview）

**注意：**脚本会自动从 .env 加载 API 密钥。不要手动检查 API 密钥，也不要询问用户；直接运行脚本，如果缺少密钥，脚本会报错并提供说明。

意图识别

分析用户请求以确定意图：

意图	触发词	操作
生成	“create”“generate”“make”“draw”“design”	文本生成图像
编辑	“edit”“change”“modify”“update”“fix”	图像生成图像
透明度	“transparent”“remove background”“alpha”“cutout”“PNG with transparency”	使用差异抠图
文字叠加	“add text”“write on”“label”“caption”	使用 Gemini 3 Pro 准确生成文字

分辨率选择

根据用途选择分辨率：

分辨率	适用场景	像素输出
1K	快速预览、缩略图、网页图标	~1024px
2K	社交媒体、标准网页图像	~2048px
4K	印刷、专业素材、精灵图集	~4096px

经验法则：

• 精灵图集、游戏素材、印刷材料 → 4K
• 社交媒体、博客图片、演示文稿 → 2K
• 快速测试、缩略图、原型 → 1K

不确定时，询问用户或默认使用 2K。

宽高比

可用选项：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9

选择指南：

• 方形内容（图标、头像、社交帖子）→ 1:1
• 纵向内容（移动端、竖屏视频）→ 9:16 或 3:4
• 横向内容（桌面端、演示文稿）→ 16:9 或 3:2
• 电影感／超宽屏 → 21:9

核心实现

基础生成

from google import genai
from google.genai import types
from PIL import Image
import io

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="Your descriptive prompt here",
    config=types.GenerateContentConfig(
        response_modalities=['IMAGE'],
        image_config=types.ImageConfig(
            aspect_ratio="1:1",  # or other ratio
            image_size="2K"     # 1K, 2K, or 4K
        ),
    ),
)

# Extract image from response
for part in response.parts:
    if part.inline_data is not None:
        image = Image.open(io.BytesIO(part.inline_data.data))
        image.save("output.png")
        break

图像编辑

# Load existing image
input_image = Image.open("input.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        input_image,
        "Edit instruction: Change the background to sunset colors"
    ],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        image_config=types.ImageConfig(
            aspect_ratio="1:1",
            image_size="2K"
        ),
    ),
)

多轮编辑

使用思维签名保留编辑上下文：

# First edit
response1 = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[image, "Add a red hat"],
    config=config,
)

# Continue editing (include previous response)
response2 = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        image,
        "Add a red hat",
        response1,  # Include for context preservation
        "Now make the hat blue instead"
    ],
    config=config,
)

透明度提取

用户需要透明图像时，使用差异抠图。参见 scripts/transparency.py。

适用场景：

• 用户明确要求透明背景
• 游戏精灵、图标、徽标
• 将用于合成的素材
• 抠图和贴纸

流程：

1. 在纯白背景（#FFFFFF）上生成图像
2. 将同一图像编辑为纯黑背景（#000000）
3. 根据像素差异计算 Alpha 值
4. 恢复原始颜色

**关键原理：**不透明像素在两种背景上看起来相同（距离 ≈ 0）；透明像素会显示背景色（最大距离）。

from scripts.transparency import extract_alpha_difference_matting

# After generating white and black background versions
final_image = extract_alpha_difference_matting(img_on_white, img_on_black)
final_image.save("output.png")  # RGBA with true transparency

提示词工程

基本原则

“描述场景，而不只是罗列关键词。”

叙述性段落优于互不相关的词语列表。

有效的提示词结构

[Style/Medium] of [Subject] in [Context/Setting], [Lighting], [Additional details]

示例：

# Photorealistic
A professional studio photograph of a brass steampunk pocket watch,
shot with a 50mm lens, soft diffused lighting from the left,
shallow depth of field with bokeh background, 4K HDR quality.

# Illustration
A detailed digital illustration of a medieval blacksmith's forge,
isometric perspective, warm orange glow from the furnace,
dieselpunk aesthetic with exposed pipes and riveted metal plates.

# Product mockup
A product photography shot of a ceramic coffee mug on a marble surface,
natural window lighting, minimalist Scandinavian style, clean white background.

图像中的文字

对于包含文字的图像，请使用 Gemini 3 Pro（而非 Imagen）：

• 每个文字元素不超过 25 个字符
• 最多使用 2～3 个不同的文字短语
• 大致说明字体风格（粗体、优雅、手写）
• 指明字号（小、中、大）

质量修饰词

添加以下词语以提升输出效果：

• **摄影：**4K、HDR、影棚照片、专业布光
• **艺术：**细节丰富、专业创作、高质量插画
• **通用：**高保真、细节清晰、精致成品

错误处理

from google.genai import errors

def generate_with_retry(client, *, model, contents, config, max_attempts=5):
    for attempt in range(1, max_attempts + 1):
        try:
            return client.models.generate_content(
                model=model, contents=contents, config=config
            )
        except errors.APIError as e:
            code = getattr(e, "code", None) or getattr(e, "status", None)
            if code not in (429, 500, 502, 503, 504) or attempt >= max_attempts:
                raise
            delay = min(30, 2 ** (attempt - 1))
            time.sleep(delay)

模型选择

模型	用途
gemini-3-pro-image-preview	复杂编辑、文本渲染、多轮交互、透明度工作流
gemini-2.5-flash-image	快速生成、大批量处理、简单任务
imagen-4.0-generate-001	照片级图像，无需编辑

大多数任务默认使用 gemini-3-pro-image-preview。

文件参考

• scripts/generate.py - 图像生成命令行工具（请使用此工具，而不是编写代码）
• scripts/transparency.py - 差分抠图实现
• references/prompts.md - 按类别整理的扩展提示词示例