gemini-imagegen

Gemini 图像生成（Nano Banana Pro）

使用 Google 的 Gemini API 生成和编辑图像。必须设置环境变量 GEMINI_API_KEY。

默认模型

模型	分辨率	最适用于
gemini-3-pro-image-preview	1K-4K	所有图像生成（默认）

注意： 始终使用此 Pro 模型。只有在明确要求时才使用其他模型。

快速参考

默认设置

• 模型： gemini-3-pro-image-preview
• 分辨率： 1K（默认；选项：1K、2K、4K）
• 宽高比： 1:1（默认）

可用宽高比

1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9

可用分辨率

1K（默认）、2K、4K

核心 API 模式

import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# Basic generation (1K, 1:1 - defaults)
response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["Your prompt here"],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
    ),
)

for part in response.parts:
    if part.text:
        print(part.text)
    elif part.inline_data:
        image = part.as_image()
        image.save("output.png")

自定义分辨率和宽高比

from google.genai import types

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[prompt],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",  # Wide format
            image_size="2K"       # Higher resolution
        ),
    )
)

分辨率示例

# 1K (default) - Fast, good for previews
image_config=types.ImageConfig(image_size="1K")

# 2K - Balanced quality/speed
image_config=types.ImageConfig(image_size="2K")

# 4K - Maximum quality, slower
image_config=types.ImageConfig(image_size="4K")

宽高比示例

# Square (default)
image_config=types.ImageConfig(aspect_ratio="1:1")

# Landscape wide
image_config=types.ImageConfig(aspect_ratio="16:9")

# Ultra-wide panoramic
image_config=types.ImageConfig(aspect_ratio="21:9")

# Portrait
image_config=types.ImageConfig(aspect_ratio="9:16")

# Photo standard
image_config=types.ImageConfig(aspect_ratio="4:3")

编辑图像

通过文本提示词传入现有图像：

from PIL import Image

img = Image.open("input.png")
response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["Add a sunset to this scene", img],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
    ),
)

多轮优化

使用聊天进行迭代式编辑：

from google.genai import types

chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    config=types.GenerateContentConfig(response_modalities=['TEXT', 'IMAGE'])
)

response = chat.send_message("Create a logo for 'Acme Corp'")
# Save first image...

response = chat.send_message("Make the text bolder and add a blue gradient")
# Save refined image...

提示词最佳实践

照片级真实感场景

包含相机细节：镜头类型、光线、角度和氛围。

“一张照片级真实感的特写肖像，85mm 镜头，柔和的黄金时刻光线，浅景深”

风格化艺术

明确指定风格：

“一张可爱风格的快乐小熊猫贴纸，粗线条、赛璐璐着色、白色背景”

图像中的文字

明确说明字体风格和位置：

“创建一个包含文字 ‘Daily Grind’ 的徽标，采用简洁的无衬线字体，黑白配色，咖啡豆图案”

产品模型图

描述布光设置和表面：

“在抛光混凝土表面拍摄的棚拍产品照片，采用三点柔光箱布光，45 度角”

高级功能

Google 搜索接地

根据实时数据生成图像：

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["Visualize today's weather in Tokyo as an infographic"],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        tools=[{"google_search": {}}]
    )
)

多张参考图像（最多 14 张）

组合多个来源中的元素：

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        "Create a group photo of these people in an office",
        Image.open("person1.png"),
        Image.open("person2.png"),
        Image.open("person3.png"),
    ],
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
    ),
)

重要：文件格式和媒体类型

重要： Gemini API 默认以 JPEG 格式返回图像。保存时务必使用 .jpg 扩展名，以避免媒体类型不匹配。

# CORRECT - Use .jpg extension (Gemini returns JPEG)
image.save("output.jpg")

# WRONG - Will cause "Image does not match media type" errors
image.save("output.png")  # Creates JPEG with PNG extension!

转换为 PNG（如有需要）

如果确实需要 PNG 格式：

from PIL import Image

# Generate with Gemini
for part in response.parts:
    if part.inline_data:
        img = part.as_image()
        # Convert to PNG by saving with explicit format
        img.save("output.png", format="PNG")

验证图像格式

使用 file 命令检查实际格式是否与扩展名一致：

file image.png
# If output shows "JPEG image data" - rename to .jpg!

注意事项

• 所有生成的图像都包含 SynthID 水印
• Gemini 默认返回 JPEG 格式——务必使用 .jpg 扩展名
• 仅图像模式（responseModalities: ["IMAGE"]）无法与 Google 搜索接地配合使用
• 编辑时，请用自然对话描述更改内容——模型能够理解语义遮罩
• 默认使用 1K 分辨率以提高速度；质量至关重要时使用 2K/4K