nano-banana-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nano Banana Pro (Gemini 3 Pro Image)

Nano Banana Pro（Gemini 3 Pro Image）

Generate and edit professional-quality images using Google's state-of-the-art Gemini 3 Pro Image model.

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

API Configuration

API配置

Set your Gemini API key as an environment variable:

bash

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

Get your API key at: https://aistudio.google.com/apikey

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

bash

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

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

Quick Start

快速开始

Test API Connection

测试API连接

Before generating images, verify API credentials:

bash

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

Or set environment variable:

bash

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

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

bash

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

或设置环境变量后执行：

bash

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

Generate Image from Text

根据文本生成图像

bash

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

With options:

bash

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

bash

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

带可选参数：

bash

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

Edit Existing Image

编辑现有图像

bash

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

With options:

bash

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

bash

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

带可选参数：

bash

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

Core Workflows

核心工作流

1. Text-to-Image Generation

1. 文本转图像生成

When to use: Creating images from scratch based on text descriptions.

Process:

Craft effective prompt using best practices from
```
references/prompting-guide.md
```
Run generation script with appropriate parameters
Review output and iterate if needed

Example:

bash

undefined

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

流程：

撰写有效提示词，参考
```
references/prompting-guide.md
```
中的最佳实践
运行生成脚本并设置合适参数
查看输出结果，如有需要进行迭代优化

示例：

bash

undefined

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


**Key considerations**:
- Use specific, detailed prompts (see [Prompting Best Practices](#prompting-best-practices))
- Choose appropriate aspect ratio for use case
- Lower temperature (0.3-0.5) for consistency, higher (0.8-1.0) for creativity
- Iterate with multi-turn editing for complex requirements


**关键注意事项**：
- 使用具体、详细的提示词（参见[提示词最佳实践](#prompting-best-practices)）
- 根据使用场景选择合适的宽高比
- 较低的temperature值（0.3-0.5）保证一致性，较高值（0.8-1.0）提升创意性
- 复杂需求可通过多轮编辑迭代实现

2. Image Editing & Refinement

2. 图像编辑与优化

When to use: Modifying existing images with natural language instructions.

Process:

Identify specific changes needed
Use precise editing instructions with action verbs (Add, Change, Make, Remove, Replace)
Run edit script with source image
Chain multiple edits for complex transformations

Example - Single Edit:

bash

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

Example - Multi-turn refinement:

bash

undefined

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

流程：

明确需要修改的具体内容
使用精准的编辑指令，包含动作动词（添加、修改、调整、移除、替换）
运行编辑脚本并传入源图像
链式执行多次编辑实现复杂变换

示例 - 单次编辑：

bash

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

示例 - 多轮优化：

bash

undefined

Edit 1: Change time of day

编辑1：更改时间场景

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

编辑2：基于第一步输出添加元素

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

编辑3：微调氛围

python scripts/edit_image.py "Make the sky more orange and dramatic" ./step2/with_lamps_image_0_0.jpg
--output ./final --filename final


**Key considerations**:
- Be specific about which elements to change
- Use positional language ("in the background", "on the left")
- Keep original aspect ratio unless intentionally changing
- Each edit builds on previous result

python scripts/edit_image.py "Make the sky more orange and dramatic" ./step2/with_lamps_image_0_0.jpg
--output ./final --filename final


**关键注意事项**：
- 明确说明需要修改的元素
- 使用位置描述（如“背景中”、“左侧”）
- 除非有意更改，否则保持原始宽高比
- 每次编辑基于上一次的结果

3. Batch Generation

3. 批量生成

When to use: Generating multiple variations or different images in sequence.

Process:

Create a shell script or Python wrapper:

bash

#!/bin/bash

适用场景：批量生成多个变体或不同图像。

流程：

创建Shell脚本或Python包装器：

bash

#!/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

undefined

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

undefined

4. Reference-Based Generation

4. 基于参考图生成

When to use: Maintaining style consistency or character consistency across images.

Process:

Prepare reference images (up to 14 images)
Create prompt referencing style/character to maintain
Use Python SDK or API directly for multi-image upload

Example using Python:

python

from generate_image import NanoBananaProClient
from pathlib import Path
import base64

client = NanoBananaProClient(api_key="YOUR_KEY")

适用场景：保持图像间的风格一致性或角色一致性。

流程：

准备参考图像（最多14张）
创建提示词，指明需要保持的风格/角色
直接使用Python SDK或API上传多张图像

Python示例：

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)

(需要直接调用API并传入多个inlineData部分)

undefined

undefined

Prompting Best Practices

提示词最佳实践

Essential Structure

基本结构

Follow this formula for best results:

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

Example:

"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"

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

[主体] + [风格/媒介] + [光线细节] + [相机/构图] + [质量修饰词]

示例：

"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"

Key Principles

核心原则

Be Specific: Vague prompts → generic results
- ❌ "a sunset"
- ✅ "golden hour sunset over mountain range, vibrant orange and purple clouds, silhouetted pine trees in foreground"
Use Cinematic Language: Nano Banana Pro responds well to photography terms
- Lens: "24mm wide-angle" | "85mm portrait" | "200mm telephoto"
- Lighting: "soft diffused" | "harsh direct" | "backlit with rim lighting"
- Camera: "low-angle shot" | "overhead view" | "Dutch angle tilt"
Layer Descriptions: Build depth with atmosphere, materials, mood
- "Cozy library, warm amber lighting, leather chairs, rain visible through tall windows, steam rising from tea cup on oak table"
Iterate with Multi-Turn: Start simple, refine progressively
- Turn 1: "Modern kitchen, white cabinets"
- Turn 2: "Add marble countertops"
- Turn 3: "Make the lighting warmer, golden hour through windows"

具体明确：模糊的提示词会导致通用化结果
- ❌ "a sunset"
- ✅ "golden hour sunset over mountain range, vibrant orange and purple clouds, silhouetted pine trees in foreground"
使用影视摄影术语：Nano Banana Pro对摄影术语响应良好
- 镜头："24mm wide-angle" | "85mm portrait" | "200mm telephoto"
- 光线："soft diffused" | "harsh direct" | "backlit with rim lighting"
- 拍摄角度："low-angle shot" | "overhead view" | "Dutch angle tilt"
分层描述：通过氛围、材质、情绪构建画面深度
- "Cozy library, warm amber lighting, leather chairs, rain visible through tall windows, steam rising from tea cup on oak table"
多轮迭代：从简单提示开始，逐步细化
- 第一轮："Modern kitchen, white cabinets"
- 第二轮："Add marble countertops"
- 第三轮："Make the lighting warmer, golden hour through windows"

Cinematic Digital Painting Style

影视级数字绘画风格

For documentary-style digital paintings with warm golden lighting, painterly brush strokes, and atmospheric depth, see the dedicated style guide:

cinematic-style.md
- Complete formula, key elements, examples, and technical notes

Quick reference:

Warm golden/amber lighting with dramatic rim lighting
Painterly brush strokes with visible texture
Soft bokeh depth-of-field for atmospheric background blur
High contrast (deep blacks + bright highlights)
Temperature: 0.6 for balanced consistency/creativity

For complete prompting guide, see:

references/prompting-guide.md

如需创建具有暖金色光线、绘画笔触和氛围深度的纪录片风格数字绘画，请参考专门的风格指南：

cinematic-style.md
- 完整公式、核心元素、示例及技术说明

快速参考：

暖金色/琥珀色光线，搭配戏剧性轮廓光
带有可见纹理的绘画笔触
柔和的背景虚化（Bokeh）以营造氛围
高对比度（深黑色+明亮高光）
Temperature值：0.6（平衡一致性与创意性）

完整提示词指南请查看：

references/prompting-guide.md

Script Reference

脚本参考

generate_image.py

Generate images from text prompts.

Parameters:

```
prompt
```
(required): Text description of image
```
--api-key
```
: API key (or use
```
GEMINI_API_KEY
```
env var)
```
--aspect-ratio
```
: 1:1 | 3:4 | 4:3 | 9:16 | 16:9 (default: 16:9)
```
--temperature
```
: 0.0-1.0 (default: 0.7)
```
--output
```
: Output directory (default: ./output)
```
--filename
```
: Base filename (default: generated)
```
--verbose
```
: Show full API response

Common use cases:

bash

undefined

根据文本提示生成图像。

参数：

```
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响应

常见使用场景：

bash

undefined

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

undefined

python scripts/generate_image.py "test prompt" --verbose

undefined

edit_image.py

Edit existing images with natural language instructions.

Parameters:

```
prompt
```
(required): Edit instruction
```
image
```
(required): Path to input image
```
--api-key
```
: API key (or use
```
GEMINI_API_KEY
```
env var)
```
--aspect-ratio
```
: Output aspect ratio
```
--temperature
```
: Creativity level
```
--output
```
: Output directory (default: ./output)
```
--filename
```
: Base filename (default: edited)
```
--verbose
```
: Show full API response

Common editing patterns:

bash

undefined

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

参数：

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

常见编辑模式：

bash

undefined

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

undefined

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

undefined

test_connection.py

Test API connectivity and verify credentials.

Parameters:

```
--api-key
```
: API key to test
```
--json
```
: Output as JSON for scripting

Usage:

bash

undefined

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

参数：

```
--api-key
```
：待测试的API密钥
```
--json
```
：以JSON格式输出结果（适用于脚本）

用法：

bash

undefined

Interactive test

交互式测试

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

Automated testing

自动化测试

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

undefined

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

undefined

generate_with_references.py

Generate images using style reference images (up to 14).

Parameters:

```
prompt
```
(required): Text description of image to generate
```
references
```
(required): One or more reference image paths (up to 14)
```
--api-key
```
: API key (or use
```
GEMINI_API_KEY
```
env var)
```
--aspect-ratio
```
: 1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9 (default: 1:1)
```
--resolution
```
: 1K | 2K | 4K (default: 2K)
```
--output
```
: Output directory (default: ./output)
```
--filename
```
: Base filename (default: generated)
```
--verbose
```
: Show detailed output

Usage:

bash

undefined

基于风格参考图生成图像（最多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
```
：显示详细输出

用法：

bash

undefined

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


**Best practices**:
- Include style description in prompt ("same artistic style", "match the lighting")
- Use consistent reference images (same art style, lighting, color palette)
- Reference images can include characters, objects, or style examples
- Up to 14 images: 6 for objects, 5 for character consistency

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张用于角色一致性

Advanced Techniques

高级技巧

Multi-Resolution Workflow

多分辨率工作流

Generate quick previews, then upscale finals:

bash

undefined

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

bash

undefined

1. Quick iteration at 1K (implied by default, fastest)

1. 以1K分辨率快速迭代（默认设置，速度最快）

python scripts/generate_image.py "concept art spaceship"
--filename concept_draft

2. Review output, refine prompt

2. 查看输出，优化提示词

3. Generate final at higher quality with refined prompt

3. 使用优化后的提示词生成高质量最终版本

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

undefined

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

undefined

Temperature Strategies

Temperature值策略

0.3-0.5: Product photography, technical diagrams, consistency required
0.7 (default): Balanced - most use cases
0.8-0.9: Creative exploration, artistic styles, abstract art

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

Aspect Ratio Selection

宽高比选择

1:1 - Social media posts, profile images, icons
16:9 - Presentations, YouTube thumbnails, website headers
9:16 - Mobile stories, vertical video thumbnails, app screens
4:3 / 3:4 - Traditional photography, portrait work
4:5 - Instagram posts (use 4:3 as closest)

1:1 - 社交媒体帖子、头像、图标
16:9 - 演示文稿、YouTube缩略图、网站页眉
9:16 - 移动端故事、竖版视频缩略图、应用界面
4:3 / 3:4 - 传统摄影、人像作品
4:5 - Instagram帖子（可使用4:3作为近似值）

Troubleshooting

故障排查

Common Issues

常见问题

API Key Not Working

bash

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

Rate Limiting
- Free tier: ~100 requests/day, 2-5/minute
- Add delays between requests:
```
sleep 2
```
- Implement exponential backoff (see
```
references/troubleshooting.md
```
  )
Low Quality Output
- Use more specific prompts
- Lower temperature for consistency (0.5)
- Add quality modifiers: "4K", "professional", "sharp focus"
- Check input image resolution (editing)
Model Not Found (404)
- Verify model name:
```
gemini-3-pro-image-preview
```
- Check if geo-blocked (Europe/MENA)
- Try VPN or alternative model
Content Policy Violation
- Remove references to violence, explicit content
- Avoid copyrighted characters
- Don't reference real public figures without permission
- Rephrase to be less explicit

For detailed troubleshooting, see:

references/troubleshooting.md

API密钥无效

bash

# 验证密钥格式并测试
python scripts/test_connection.py --api-key YOUR_KEY

请求频率限制
- 免费 tier：约100次请求/天，2-5次请求/分钟
- 在请求间添加延迟：
```
sleep 2
```
- 实现指数退避策略（参见
```
references/troubleshooting.md
```
  ）
输出质量低
- 使用更具体的提示词
- 降低temperature值以保证一致性（0.5）
- 添加质量修饰词：“4K”、“professional”、“sharp focus”
- 检查输入图像分辨率（编辑场景）
模型未找到（404错误）
- 验证模型名称：
```
gemini-3-pro-image-preview
```
- 检查是否受地域限制（欧洲/中东及北非地区）
- 尝试使用VPN或替代模型
内容政策违规
- 移除涉及暴力、露骨内容的描述
- 避免使用受版权保护的角色
- 未经许可不要引用真实公众人物
- 重新措辞以降低明确性

详细故障排查指南请查看：

references/troubleshooting.md

API Details

API详情

Pricing

定价

1K/2K images: $0.134 per image
4K images: $0.24 per image
Image inputs (editing): $0.0011 per image

1K/2K图像：每张0.134美元
4K图像：每张0.24美元
图像输入（编辑场景）：每张0.0011美元

Rate Limits

请求频率限制

Free Tier:

~100 requests/day
2-5 requests/minute
1 concurrent request

Paid Tier:

Unlimited daily (subject to quota)
60 requests/minute
10 concurrent requests

免费Tier:

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

付费Tier:

每日请求无限制（受配额约束）
60次请求/分钟
10次并发请求

Supported Formats

支持的格式

Input (editing): JPEG, PNG, WebP Output: JPEG, PNG (specified via API)

For complete API reference, see:

references/api-reference.md

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

完整API参考请查看：

references/api-reference.md

Integration Patterns

集成模式

Python Integration

Python集成

python

from scripts.generate_image import NanoBananaProClient

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}")

undefined

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

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

undefined

Bash/Shell Workflows

Bash/Shell工作流

bash

#!/bin/bash

bash

#!/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"

undefined

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"

undefined

Error Handling Pattern

错误处理模式

python

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")

python

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):  # 频率限制
                wait = 2 ** attempt  # 指数退避
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

Example Use Cases

示例用例

Marketing Campaign

营销活动

bash

undefined

bash

undefined

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

undefined

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

undefined

Content Creation

内容创作

bash

undefined

bash

undefined

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

undefined

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

undefined

Product Mockups

产品样机

bash

undefined

bash

undefined

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

undefined

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

undefined

Resources

资源

Documentation Files

文档文件

Prompting Guide (
```
references/prompting-guide.md
```
): Best practices, examples, techniques
API Reference (
```
references/api-reference.md
```
): Complete API documentation, pricing, SDKs
Troubleshooting (
```
references/troubleshooting.md
```
): Common issues, solutions, error codes
Example Prompts (
```
assets/example-prompts.md
```
): Ready-to-use prompts by category
Aldea Avatars (
```
references/aldea-avatars.md
```
): Character templates for Soul Engine personas

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

External Links

外部链接

Google AI Studio: https://aistudio.google.com (get API key, free tier)
Official Docs: https://ai.google.dev/gemini-api/docs
Pricing Page: https://ai.google.dev/gemini-api/docs/pricing
Model Info: https://deepmind.google/models/gemini-image/pro/
Vertex AI Console: https://console.cloud.google.com/vertex-ai (enterprise)

Google AI Studio：https://aistudio.google.com（获取API密钥、免费Tier）
官方文档：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（企业级）

Getting API Key

获取API密钥

Visit https://aistudio.google.com
Sign in with Google account
Click "Get API key" in left sidebar
Create new project or select existing
Generate API key
Store securely (never commit to git)

bash

undefined

访问https://aistudio.google.com
使用Google账号登录
点击左侧边栏的“Get API key”
创建新项目或选择现有项目
生成API密钥
安全存储（切勿提交到git）

bash

undefined

Store in environment

存储到环境变量

export GEMINI_API_KEY="AIzaSy..."

Or in .env file (add to .gitignore!)

或存储到.env文件（需添加到.gitignore！）

echo "GEMINI_API_KEY=AIzaSy..." >> .env

undefined

echo "GEMINI_API_KEY=AIzaSy..." >> .env

undefined

Tips & Tricks

技巧与窍门

Cache results: Avoid regenerating identical images
Use templates: Create prompt templates for repeated use cases
Iterate gradually: Start simple, refine with multi-turn editing
Batch carefully: Add delays to respect rate limits
Monitor costs: 4K images cost 2x more than 2K
Test prompts: Use low temperature for consistency testing
Learn from examples: Study
```
assets/example-prompts.md
```
for patterns
Reference images: Use up to 14 for style consistency
Quality modifiers: Always include "professional", "4K", "sharp" for best results
Verbose mode: Use
```
--verbose
```
flag when debugging

缓存结果：避免重复生成相同图像
使用模板：为重复使用的场景创建提示词模板
逐步迭代：从简单提示开始，通过多轮编辑细化
谨慎批量处理：添加延迟以遵守频率限制
监控成本：4K图像的成本是2K图像的2倍
测试提示词：使用低temperature值进行一致性测试
学习示例：研究
```
assets/example-prompts.md
```
中的模式
参考图像：最多使用14张以保持风格一致性
质量修饰词：始终包含“professional”、“4K”、“sharp”以获得最佳结果
详细模式：调试时使用
```
--verbose
```
标志