nano-banana-pro

Nano Banana Pro（Gemini 3 Pro Image）

使用 Google 最先进的 Gemini 3 Pro Image 模型，生成和编辑专业品质的图像。

API 配置

将 Gemini API 密钥设置为环境变量：

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

在此获取 API 密钥：https://aistudio.google.com/apikey

快速入门

测试 API 连接

生成图像前，请验证 API 凭据：

python scripts/test_connection.py --api-key YOUR_KEY

或者设置环境变量：

export GEMINI_API_KEY="your-api-key-here"
python scripts/test_connection.py

根据文本生成图像

python scripts/generate_image.py "A futuristic cityscape at sunset, neon lights, cyberpunk style"

使用选项：

python scripts/generate_image.py "Portrait of a cat" \
  --aspect-ratio 9:16 \
  --temperature 0.7 \
  --output ./my_images \
  --filename cat_portrait

编辑现有图像

python scripts/edit_image.py "Make the sky more dramatic with storm clouds" input.jpg

使用选项：

python scripts/edit_image.py "Change car color to red" photo.png \
  --aspect-ratio 16:9 \
  --output ./edited \
  --filename red_car

核心工作流

1. 文生图

适用场景：根据文本描述从头创建图像。

流程：

1. 撰写有效的提示词，参考 references/prompting-guide.md 中的最佳实践
2. 运行生成脚本，并设置适当的参数
3. 检查输出结果，并在需要时迭代

示例：

# High-quality product photography
python scripts/generate_image.py \
  "High-end product photography of luxury watch on black marble, dramatic single key light from top-left, reflective surface, macro lens, f/5.6, commercial quality, 4K" \
  --aspect-ratio 1:1 \
  --temperature 0.5

重要注意事项：

• 使用具体、详细的提示词（参见提示词最佳实践）
• 根据使用场景选择合适的宽高比
• 较低的 temperature（0.3-0.5）可提高一致性，较高的 temperature（0.8-1.0）则更具创造性
• 对于复杂要求，可通过多轮编辑进行迭代

2. 图像编辑与优化

适用场景：使用自然语言指令修改现有图像。

流程：

1. 确定需要进行的具体更改
2. 使用带有动作动词（Add、Change、Make、Remove、Replace）的精确编辑指令
3. 运行编辑脚本并提供源图像
4. 对于复杂的变换，串联多次编辑

示例 - 单次编辑：

python scripts/edit_image.py \
  "Add flying birds in the upper right sky" \
  landscape.jpg \
  --output ./edited

示例 - 多轮优化：

# Edit 1: Change time of day
python scripts/edit_image.py "Convert to sunset lighting" day_scene.jpg \
  --output ./step1 --filename sunset

# Edit 2: Add elements using output from step 1
python scripts/edit_image.py "Add warm street lamps glowing" ./step1/sunset_image_0_0.jpg \
  --output ./step2 --filename with_lamps

# Edit 3: Fine-tune atmosphere
python scripts/edit_image.py "Make the sky more orange and dramatic" ./step2/with_lamps_image_0_0.jpg \
  --output ./final --filename final

重要注意事项：

• 明确指出要更改的元素
• 使用位置描述（“在背景中”“在左侧”）
• 除非有意更改，否则保留原始宽高比
• 每次编辑都会基于上一次的结果进行

3. 批量生成

适用场景：按顺序生成多个变体或不同图像。

流程：

创建 shell 脚本或 Python 封装程序：

#!/bin/bash
# batch_generate.sh

PROMPTS=(
  "Modern office workspace, minimalist design"
  "Cozy coffee shop interior, warm lighting"
  "Professional meeting room, corporate aesthetic"
)

for i in "${!PROMPTS[@]}"; do
  python scripts/generate_image.py "${PROMPTS[$i]}" \
    --output ./batch_output \
    --filename "scene_$i" \
    --aspect-ratio 16:9

  echo "Generated image $((i+1))/${#PROMPTS[@]}"
  sleep 2  # Rate limiting
done

4. 基于参考图像生成

适用场景：在多张图像中保持风格或角色一致。

流程：

1. 准备参考图像（最多 14 张）
2. 创建提示词，引用需要保持的风格或角色
3. 对于多图像上传，直接使用 Python SDK 或 API

Python 示例：

from generate_image import NanoBananaProClient
from pathlib import Path
import base64

client = NanoBananaProClient(api_key="YOUR_KEY")

# Read reference images
ref_images = []
for img_path in ["ref1.jpg", "ref2.jpg", "ref3.jpg"]:
    with open(img_path, "rb") as f:
        img_data = base64.b64encode(f.read()).decode()
        ref_images.append({
            "inlineData": {
                "mimeType": "image/jpeg",
                "data": img_data
            }
        })

# Generate with references
# (Requires direct API call with multiple inlineData parts)

提示词最佳实践

基本结构

遵循以下公式以获得最佳效果：

[Subject] + [Style/Medium] + [Lighting Details] + [Camera/Composition] + [Quality Modifiers]

示例：

"Portrait of elderly craftsman | Documentary photography style | Soft window light from left | 85mm lens, f/2.8, shallow DOF | Professional editorial quality, sharp focus on eyes"

关键原则

1. 描述具体：模糊的提示词 → 普通的结果

   • ❌ “日落”
   • ✅ “山脉上空的黄金时刻日落，鲜艳的橙色和紫色云彩，前景中是轮廓分明的松树”

2. 使用电影化语言：Nano Banana Pro 对摄影术语响应良好

   • 镜头：“24mm 广角” | “85mm 人像” | “200mm 长焦”
   • 光线：“柔和漫射” | “强烈直射” | “逆光并带有轮廓光”
   • 相机：“低角度拍摄” | “俯视图” | “荷兰角倾斜”

3. 分层描述：通过氛围、材质和情绪营造景深

   • “舒适的图书馆，温暖的琥珀色灯光，皮椅，高窗外可见雨景，橡木桌上的茶杯升起热气”

4. 通过多轮对话迭代：从简单开始，逐步优化

   • 第 1 轮：“现代厨房，白色橱柜”
   • 第 2 轮：“添加大理石台面”
   • 第 3 轮：“让灯光更温暖，窗外呈现黄金时刻的光线”

电影感数字绘画风格

如需了解具有温暖金色光线、绘画感笔触和氛围纵深的纪录片风格数字绘画，请参阅专门的风格指南：

cinematic-style.md - 完整公式、关键元素、示例和技术说明

快速参考：

• 温暖的金色／琥珀色光线，搭配戏剧性的轮廓光
• 绘画感笔触，纹理清晰可见
• 柔和的散景景深，营造氛围感背景虚化
• 高对比度（深黑色 + 明亮高光）
• 温度：0.6，平衡一致性与创造性

完整提示词指南请参阅：references/prompting-guide.md

脚本参考

generate_image.py

根据文本提示生成图像。

参数：

• prompt（必填）：图像的文本描述
• --api-key：API 密钥（或使用 GEMINI_API_KEY 环境变量）
• --aspect-ratio：1:1 | 3:4 | 4:3 | 9:16 | 16:9（默认：16:9）
• --temperature：0.0-1.0（默认：0.7）
• --output：输出目录（默认：./output）
• --filename：基础文件名（默认：generated）
• --verbose：显示完整的 API 响应

常见用例：

# Quick generation
python scripts/generate_image.py "red sports car"

# High-quality consistent output
python scripts/generate_image.py "professional headshot" \
  --temperature 0.4 --aspect-ratio 3:4

# Creative exploration
python scripts/generate_image.py "abstract art" --temperature 0.9

# Debug mode
python scripts/generate_image.py "test prompt" --verbose

edit_image.py

使用自然语言指令编辑现有图像。

参数：

• prompt（必填）：编辑指令
• image（必填）：输入图像的路径
• --api-key：API 密钥（或使用 GEMINI_API_KEY 环境变量）
• --aspect-ratio：输出宽高比
• --temperature：创造性水平
• --output：输出目录（默认：./output）
• --filename：基础文件名（默认：edited）
• --verbose：显示完整的 API 响应

常见编辑模式：

# Localized changes
python scripts/edit_image.py "Make the car red" photo.jpg

# Atmospheric changes
python scripts/edit_image.py "Convert to night scene" day.jpg

# Add elements
python scripts/edit_image.py "Add mountains in background" landscape.jpg

# Remove elements
python scripts/edit_image.py "Remove person from left side" group.jpg

# Style transforms
python scripts/edit_image.py "Apply vintage film look" modern.jpg

test_connection.py

测试 API 连通性并验证凭据。

参数：

• --api-key：要测试的 API 密钥
• --json：以 JSON 格式输出，供脚本使用

用法：

# Interactive test
python scripts/test_connection.py --api-key YOUR_KEY

# Automated testing
python scripts/test_connection.py --json | jq '.success'

generate_with_references.py

使用风格参考图像生成图像（最多 14 张）。

参数：

• prompt（必填）：要生成图像的文本描述
• references（必填）：一个或多个参考图像路径（最多 14 张）
• --api-key：API 密钥（或使用 GEMINI_API_KEY 环境变量）
• --aspect-ratio：1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9（默认：1:1）
• --resolution：1K | 2K | 4K（默认：2K）
• --output：输出目录（默认：./output）
• --filename：基础文件名（默认：generated）
• --verbose：显示详细输出

用法：

# Generate avatar matching reference style
python scripts/generate_with_references.py \
  "Portrait of elderly craftsman in same artistic style as references" \
  ref1.png ref2.jpg ref3.png \
  --output ./output \
  --filename craftsman

# Character consistency across images
python scripts/generate_with_references.py \
  "Same character in a coffee shop scene" \
  character_ref1.png character_ref2.png \
  --aspect-ratio 16:9 \
  --resolution 2K

最佳实践：

• 在提示词中加入风格描述（“相同的艺术风格”“匹配光线”）
• 使用风格一致的参考图像（艺术风格、光线和配色相同）
• 参考图像可以包含角色、物体或风格示例
• 最多使用 14 张图像：6 张用于物体，5 张用于保持角色一致性

高级技巧

多分辨率工作流

先生成快速预览，再放大最终图像：

# 1. Quick iteration at 1K (implied by default, fastest)
python scripts/generate_image.py "concept art spaceship" \
  --filename concept_draft

# 2. Review output, refine prompt

# 3. Generate final at higher quality with refined prompt
python scripts/generate_image.py "detailed concept art of sleek sci-fi spaceship, studio lighting, 4K quality, sharp details" \
  --temperature 0.5 \
  --filename concept_final

温度策略

• 0.3-0.5：产品摄影、技术图表、需要保持一致性的场景
• 0.7（默认）：均衡，适用于大多数场景
• 0.8-0.9：创意探索、艺术风格、抽象艺术

宽高比选择

• 1:1 - 社交媒体帖子、个人资料图像、图标
• 16:9 - 演示文稿、YouTube 缩略图、网站页眉
• 9:16 - 手机动态、竖屏视频缩略图、应用屏幕
• 4:3 / 3:4 - 传统摄影、人像作品
• 4:5 - Instagram 帖子（最接近的选项是 4:3）

故障排除

常见问题

1. API Key 无法使用

   # Verify key format and test
   python scripts/test_connection.py --api-key YOUR_KEY
   

2. 速率限制

   • 免费层级：约 100 次请求/天，2-5 次/分钟
   • 在请求之间添加延迟：sleep 2
   • 实现指数退避（参见 references/troubleshooting.md）

3. 输出质量较低

   • 使用更具体的提示词
   • 降低 temperature 以保持一致性（0.5）
   • 添加质量修饰词："4K"、"professional"、"sharp focus"
   • 检查输入图像分辨率（编辑时）

4. 找不到模型（404）

   • 验证模型名称：gemini-3-pro-image-preview
   • 检查是否受到地理位置限制（欧洲/中东和北非）
   • 尝试使用 VPN 或其他模型

5. 违反内容政策

   • 删除涉及暴力、露骨内容的描述
   • 避免提及受版权保护的角色
   • 未经许可，不要提及真实公众人物
   • 改用不那么露骨的措辞

如需详细的故障排除信息，请参见：references/troubleshooting.md

API 详情

定价

• 1K/2K 图像：每张图像 $0.134
• 4K 图像：每张图像 $0.24
• 图像输入（编辑）：每张图像 $0.0011

速率限制

免费层级：

• 约 100 次请求/天
• 2-5 次请求/分钟
• 1 个并发请求

付费层级：

• 每日不限量（受配额限制）
• 60 次请求/分钟
• 10 个并发请求

支持的格式

输入（编辑）：JPEG、PNG、WebP 输出：JPEG、PNG（通过 API 指定）

如需完整的 API 参考，请参见：references/api-reference.md

集成模式

Python 集成

from scripts.generate_image import NanoBananaProClient

# Initialize client
client = NanoBananaProClient(api_key="YOUR_KEY")

# Generate image
response = client.generate_image(
    prompt="Professional product photo",
    aspect_ratio="1:1",
    temperature=0.6
)

# Save results
from pathlib import Path
saved = client.save_images_from_response(
    response,
    output_dir=Path("./output"),
    base_filename="product"
)

print(f"Saved to: {saved}")

Bash/Shell 工作流

#!/bin/bash
# Simple workflow automation

export GEMINI_API_KEY="your-key"

# Generate multiple variations
for style in "modern" "vintage" "minimal"; do
  python scripts/generate_image.py \
    "$style office interior" \
    --filename "office_${style}" \
    --output ./variations
  sleep 2
done

echo "Generated ${#styles[@]} variations"

错误处理模式

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.generate_image(prompt)
            return response
        except Exception as e:
            if "429" in str(e):  # Rate limited
                wait = 2 ** attempt  # Exponential backoff
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

示例用例

营销活动

# Generate hero image
python scripts/generate_image.py \
  "Dynamic marketing hero image for tech startup, modern professional team collaborating, bright office space, cinematic color grading, 16:9" \
  --temperature 0.6 \
  --output ./campaign \
  --filename hero

# Generate social media variant
python scripts/edit_image.py \
  "Crop to square focusing on center, increase contrast" \
  ./campaign/hero_image_0_0.jpg \
  --aspect-ratio 1:1 \
  --output ./campaign \
  --filename social

内容创作

# Blog header
python scripts/generate_image.py \
  "Blog header for article about sustainable architecture, modern green building with vertical gardens, clear sky, professional editorial photography, 16:9" \
  --filename blog_header

# Thumbnail for video
python scripts/generate_image.py \
  "YouTube thumbnail style, bold composition about productivity tips, vibrant colors, text space on left third, eye-catching" \
  --aspect-ratio 16:9 \
  --filename thumbnail

产品模型图

# Product shot
python scripts/generate_image.py \
  "High-end product photography of minimalist desk lamp on marble surface, soft studio lighting from right, black background, commercial quality" \
  --aspect-ratio 1:1 \
  --temperature 0.4 \
  --filename product_main

# Lifestyle context
python scripts/edit_image.py \
  "Place in modern home office setting with laptop and plants" \
  product_main_image_0_0.jpg \
  --filename product_lifestyle

资源

文档文件

• 提示词指南（references/prompting-guide.md）：最佳实践、示例和技巧
• API 参考（references/api-reference.md）：完整的 API 文档、定价和 SDK
• 故障排除（references/troubleshooting.md）：常见问题、解决方案和错误代码
• 示例提示词（assets/example-prompts.md）：按类别整理的即用型提示词
• Aldea 头像（references/aldea-avatars.md）：Soul Engine 人设的角色模板

外部链接

• Google AI Studio：https://aistudio.google.com（获取 API Key，免费层级）
• 官方文档：https://ai.google.dev/gemini-api/docs
• 定价页面：https://ai.google.dev/gemini-api/docs/pricing
• 模型信息：https://deepmind.google/models/gemini-image/pro/
• Vertex AI 控制台：https://console.cloud.google.com/vertex-ai（企业版）

获取 API Key

1. 访问 https://aistudio.google.com
2. 使用 Google 账号登录
3. 点击左侧边栏中的"Get API key"
4. 创建新项目或选择现有项目
5. 生成 API Key
6. 安全存储（切勿提交到 git）

# Store in environment
export GEMINI_API_KEY="AIzaSy..."

# Or in .env file (add to .gitignore!)
echo "GEMINI_API_KEY=AIzaSy..." >> .env

提示与技巧

1. 缓存结果：避免重复生成相同图像
2. 使用模板：为重复用例创建提示词模板
3. 逐步迭代：从简单内容开始，通过多轮编辑逐步完善
4. 谨慎批处理：添加延迟以遵守速率限制
5. 监控成本：4K 图像的费用是 2K 图像的 2 倍
6. 测试提示词：使用较低的 temperature 测试一致性
7. 从示例中学习：查看 assets/example-prompts.md 了解相关模式
8. 参考图像：最多使用 14 张图像来保持风格一致
9. 质量修饰词：始终包含 "professional"、"4K"、"sharp"，以获得最佳效果
10. 详细模式：调试时使用 --verbose 标志