gemini-imagegen

用途

gemini-imagegen 用于通过 Google 的 Gemini API（Nano Banana Pro）生成和编辑图像。它适用于以下场景：根据文本提示创建图像、编辑已有图像，以及通过多轮对话迭代优化图像。使用前必须设置环境变量 GEMINI_API_KEY。

主要能力

默认模型与设置

默认模型为 gemini-3-pro-image-preview，适用于所有图像生成任务。除非明确要求，否则应始终使用该 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 用法

基础生成（默认 1K、1:1）：

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

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

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

高级功能

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'],
    ),
)

提示词最佳实践

照片级真实场景：包含相机细节，如镜头类型、光线、角度、氛围。示例：“A photorealistic close-up portrait, 85mm lens, soft golden hour light, shallow depth of field”。
风格化艺术：明确指定风格。示例：“A kawaii-style sticker of a happy red panda, bold outlines, cel-shading, white background”。
图像中的文字：明确说明字体风格与位置。示例：“Create a logo with text 'Daily Grind' in clean sans-serif, black and white, coffee bean motif”。
产品效果图：描述布光与表面。示例：“Studio-lit product photo on polished concrete, three-point softbox setup, 45-degree angle”。

文件格式与媒体类型（重要）

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 格式，可显式转换：

from PIL import Image

for part in response.parts:
    if part.inline_data:
        img = part.as_image()
        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。
使用前必须设置环境变量 GEMINI_API_KEY。