Image Generation

Image Generation with Gemini

Use this skill when the user asks to generate or edit images with Gemini using the Python SDK. Default to gemini-3-pro-image-preview, and mention gemini-2.5-flash-image only as an optional faster/cheaper alternative.

Workflow

1) Identify task type (text-to-image, edit, or multi-reference). 2) Ensure GEMINI_API_KEY is available (env or stored in .env), then use the Python SDK. This will make network requests to the Gemini API 3) Choose model + output (response_modalities=["IMAGE"] if image-only) and run. Generation can take ~30 seconds; allow 30–60 seconds before retrying. 4) Save returned images with part.as_image(); if none, report a clear error.

Use these references

• references/python.md for Python SDK usage

Response handling (Python SDK)

Use part.as_image() to access image outputs and save them. If no image parts are returned, surface a clear error and suggest checking the API key, model name, and response modalities.

Timing note

Image generation may take around 30 seconds. When running commands via the shell tool, set a longer timeout (e.g., 60–120 seconds) to avoid premature timeouts.

REST / curl

Quickstart requirements

• A Gemini API key is required; first check the environment or a local .env file. If missing, set it in the environment as GEMINI_API_KEY.

export GEMINI_API_KEY="YOUR_API_KEY"

Recommended curl timeout

Image generation can take 20–30s. To reduce retries, set a higher client timeout (e.g. 45–60s). When running commands via tools, align the tool's overall timeout with --max-time (default 60s unless the user asks otherwise).

# Example: set a 60s total timeout for the request
curl --max-time 60 ...

Models

• Default: gemini-3-pro-image-preview (higher fidelity, 1K/2K/4K output).
• Optional: gemini-2.5-flash-image (faster/cheaper; best with <=3 input images).

Limits and notes

• gemini-3-pro-image-preview supports up to 14 reference images total, including up to 6 object images (high fidelity) and up to 5 human images for consistency.
• gemini-3-pro-image-preview supports 5 images with high fidelity and up to 14 images total. gemini-2.5-flash-image works best with up to 3 input images.
• Inline image data is intended for smaller files; keep total request size under 20 MB.
• Image generation does not support audio or video inputs.
• The model may not follow an exact requested number of outputs.
• Best results: generate the exact text first, then ask for an image with that text.
• All generated images include a SynthID watermark.

Output modalities

The model defaults to returning both text and images. To return only images:

"generationConfig": {"responseModalities": ["IMAGE"]}

Aspect ratios and image size

• Default output: if no input image, a 1:1 square; if input image is provided, output often matches its size.
• Aspect ratios: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9".
• gemini-3-pro-image-preview supports imageSize "1K", "2K", or "4K" (uppercase K required).

Text-to-image (image-only)

curl --max-time 60 "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [{"parts": [{"text": "A matte product shot of a green hiking backpack"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "4:5", "imageSize": "1K"}
    }
  }'

Image edit (text + inline image)

IMG_B64=$(base64 -w 0 input.png)

curl --max-time 60 "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [{"parts": [
      {"text": "Make the sky pastel pink"},
      {"inlineData": {"mimeType": "image/png", "data": "'"$IMG_B64"'"}}
    ]}],
    "generationConfig": {"responseModalities": ["IMAGE"]}
  }'

Multi-reference composition

IMG1=$(base64 -w 0 p1.png)
IMG2=$(base64 -w 0 p2.png)
IMG3=$(base64 -w 0 p3.png)

curl --max-time 60 "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [{"parts": [
      {"text": "Compose a single scene that keeps the people consistent."},
      {"inlineData": {"mimeType": "image/png", "data": "'"$IMG1"'"}},
      {"inlineData": {"mimeType": "image/png", "data": "'"$IMG2"'"}},
      {"inlineData": {"mimeType": "image/png", "data": "'"$IMG3"'"}}
    ]}],
    "generationConfig": {"responseModalities": ["IMAGE"]}
  }'

Grounding with Google Search

Use Google Search when the prompt needs real-time facts. Note: image-based search results are not passed to the generation model and are excluded from the response.

curl --max-time 60 "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [{"parts": [{"text": "Generate a visual moodboard for today's top space news"}]}],
    "tools": [{"google_search": {}}],
    "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "16:9"}}
  }'

Response handling

Images are returned in candidates[0].content.parts[*].inlineData (base64 bytes). Iterate parts and decode the data field to save images.

Python (google-genai)

Quickstart requirements

• A Gemini API key is required; first check the environment or a local ./.env file. The SDK reads GEMINI_API_KEY from the environment by default. If you still need an API key, ask for user Support.
• Install the Python SDK (Python 3.9+):

pip install -q -U google-genai

Models

• Default: gemini-3-pro-image-preview (higher fidelity, 1K/2K/4K output).
• Optional: gemini-2.5-flash-image (faster/cheaper; best with <=3 input images).

Limits and notes

• gemini-3-pro-image-preview supports up to 14 reference images total, including up to 6 object images (high fidelity) and up to 5 human images for consistency.
• gemini-3-pro-image-preview supports 5 images with high fidelity and up to 14 images total. gemini-2.5-flash-image works best with up to 3 input images.
• Image generation does not support audio or video inputs.
• The model may not follow an exact requested number of outputs.
• Best results: generate the exact text first, then ask for an image with that text.
• All generated images include a SynthID watermark.

Output modalities

The model defaults to returning both text and images. To return only images:

config=types.GenerateContentConfig(response_modalities=["IMAGE"])

Aspect ratios and image size

• Default output: if no input image, a 1:1 square; if input image is provided, output often matches its size.
• Aspect ratios: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9".
• gemini-3-pro-image-preview supports image_size "1K", "2K", or "4K" (uppercase K required).

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="A cinematic landscape photo at sunrise",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="2K",
        ),
    ),
)

for part in response.parts:
    if image := part.as_image():
        image.save("landscape.png")

Text-to-image

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="A minimal poster of a retro espresso machine, orange and teal",
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

for part in response.parts:
    if image := part.as_image():
        image.save("poster.png")

Image edit (text + image)

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

client = genai.Client()

prompt = "Replace the background with a warm sunrise, keep the subject"
image = Image.open("input.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[prompt, image],
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

for part in response.parts:
    if image := part.as_image():
        image.save("edited.png")

Multi-reference composition

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

client = genai.Client()

prompt = "Compose a single scene that keeps the people consistent."
images = [Image.open(p) for p in ["p1.png", "p2.png", "p3.png"]]

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[prompt, *images],
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

for part in response.parts:
    if image := part.as_image():
        image.save("composite.png")

Grounding with Google Search

Use Google Search when the prompt needs real-time facts. Note: image-based search results are not passed to the generation model and are excluded from the response.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="Visualize today's top space news as a poster",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9"),
    ),
)

for part in response.parts:
    if image := part.as_image():
        image.save("space-news.png")

# grounding metadata:
# response.candidates[0].grounding_metadata