Gemini Image Generation Skill

When to Use This Skill

• Generate images from text descriptions
• Edit existing images by adding/removing elements or changing styles
• Combine multiple source images into new compositions
• Iteratively refine images through conversational editing
• Create visual content for documentation, design, or creative projects

Prerequisites

API Key Setup

Option 1: Google AI Studio (Default)

GEMINI_API_KEY

1. Process environment:

   export GEMINI_API_KEY="your-key"

2. Project root:

   .env

3. .claude directory:

   .claude/.env

4. .claude/skills directory:

   .claude/skills/.env

5. Skill directory:

   .claude/skills/gemini-image-gen/.env

.env

GEMINI_API_KEY=your_api_key_here

Option 2: Vertex AI

# Enable Vertex AI
export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1

.env

GEMINI_USE_VERTEX=true
VERTEX_PROJECT_ID=your-gcp-project-id
VERTEX_LOCATION=us-central1

Python Setup

pip install google-genai

Quick Start

Basic Text-to-Image Generation

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

# API key detection handled automatically by helper script
client = genai.Client(api_key=os.getenv('GEMINI_API_KEY'))

response = client.models.generate_content(
    model='gemini-2.5-flash-image',
    contents='A serene mountain landscape at sunset with snow-capped peaks',
    config=types.GenerateContentConfig(
        response_modalities=['image'],
        aspect_ratio='16:9'
    )
)

# Save to ./docs/assets/
for i, part in enumerate(response.candidates[0].content.parts):
    if part.inline_data:
        with open(f'./docs/assets/generated-{i}.png', 'wb') as f:
            f.write(part.inline_data.data)

Using the Helper Script

# Generate single image
python .claude/skills/gemini-image-gen/scripts/generate.py \
  "A futuristic city with flying cars" \
  --aspect-ratio 16:9 \
  --output ./docs/assets/city.png

# Generate with specific modalities
python .claude/skills/gemini-image-gen/scripts/generate.py \
  "Modern architecture design" \
  --response-modalities image text \
  --aspect-ratio 1:1

Key Features

Aspect Ratios

Response Modalities

• ['image']

  : Generate only images

• ['text']

  : Generate only text descriptions

• ['image', 'text']

  : Generate both images and descriptions

Image Editing

import PIL.Image

img = PIL.Image.open('original.png')
response = client.models.generate_content(
    model='gemini-2.5-flash-image',
    contents=[
        'Add a red balloon floating in the sky',
        img
    ]
)

Multi-Image Composition

img1 = PIL.Image.open('background.png')
img2 = PIL.Image.open('foreground.png')

response = client.models.generate_content(
    model='gemini-2.5-flash-image',
    contents=[
        'Combine these images into a cohesive scene',
        img1,
        img2
    ]
)

Prompt Engineering Tips

1. Subject: What to generate ("a robot")
2. Context: Environmental setting ("in a futuristic city")
3. Style: Artistic treatment ("cyberpunk style, neon lighting")

• Add terms like "4K", "HDR", "high-quality", "professional photography"
• Specify camera settings: "35mm lens", "shallow depth of field", "golden hour lighting"

• Limit to 25 characters maximum
• Use up to 3 distinct phrases
• Specify font styles: "bold sans-serif title" or "handwritten script"

references/prompting-guide.md

Safety Settings

config = types.GenerateContentConfig(
    response_modalities=['image'],
    safety_settings=[
        types.SafetySetting(
            category=types.HarmCategory.HARM_CATEGORY_HATE_SPEECH,
            threshold=types.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
        )
    ]
)

references/safety-settings.md

Output Management

./docs/assets/

# Create directory if needed
mkdir -p ./docs/assets

Model Specifications

gemini-2.5-flash-image

• Input tokens: Up to 65,536
• Output tokens: Up to 32,768
• Supported inputs: Text and images
• Supported outputs: Text and images
• Knowledge cutoff: June 2025
• Features: Image generation, structured outputs, batch API, caching

Limitations

• Maximum 3 input images recommended for best results
• Text rendering works best when generated separately first
• Does not support audio/video inputs
• Regional restrictions on child image uploads (EEA, CH, UK)
• Optimal language support: English, Spanish (Mexico), Japanese, Mandarin, Hindi

Error Handling

# Check environment variables
echo $GEMINI_API_KEY

# Verify .env file exists
cat .claude/skills/gemini-image-gen/.env
# or
cat .env

• Review

  response.prompt_feedback.block_reason

• Adjust safety settings if appropriate for your use case
• Modify prompt to avoid triggering filters

• Reduce prompt length
• Use fewer input images
• Simplify image editing instructions

Reference Documentation

• references/api-reference.md

  - Complete API specifications

• references/prompting-guide.md

  - Advanced prompt engineering

• references/safety-settings.md

  - Safety configuration details

• references/code-examples.md

  - Additional implementation examples

Resources

• Official Documentation
• API Reference
• Get API Key
• Google AI Studio - Interactive testing