gemini-image-gen

name	gemini-image-gen
description	Generate images using Google's Gemini API — hero backgrounds, OG images, placeholder photos, textures, and style-matched variants. Uses free-tier models for drafts, paid for finals. No dependencies beyond Python 3. Trigger with 'generate image', 'gemini image', 'make a hero background', 'create placeholder photo', 'generate OG image', 'AI image', or 'need an image for'.
compatibility	claude-code-only

Gemini Image Generator

Generate contextual images for web projects using the Gemini API. Produces hero backgrounds, OG cards, placeholder photos, textures, and style-matched variants.

Setup

API Key: Set GEMINI_API_KEY as an environment variable. Get a key from https://aistudio.google.com/apikey if you don't have one.

export GEMINI_API_KEY="your-key-here"

Workflow

Step 1: Understand What's Needed

Gather from the user or project context:

• What: hero background, product photo, texture, OG image, placeholder
• Style: warm/cool/minimal/luxurious/bold — check project's colour palette (input.css, tailwind config)
• Dimensions: hero (1920x1080), OG (1200x630), square (1024x1024), custom
• Count: single image or multiple variants to choose from

Step 2: Build the Prompt

Use concrete photography parameters, not abstract adjectives. Read references/prompting-guide.md for the full framework.

Quick rules:

• Narrate like directing a photographer
• Use camera specs: "85mm f/1.8", "wide angle 24mm"
• Use colour anchors from the project palette: "warm terracotta (#C66A52) and cream (#F5F0EB) tones"
• Use lighting descriptions: "golden-hour light from the left, 4500K"
• Always end with: "No text, no watermarks, no logos, no hands"

Step 3: Generate

Generate a Python script (no dependencies beyond stdlib) that calls the Gemini API. The script should:

1. Read GEMINI_API_KEY from environment
2. POST to https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
3. Include "responseModalities": ["TEXT", "IMAGE"] in generationConfig
4. Parse the response: extract inlineData.data (base64) from candidate parts
5. Decode base64 and save as PNG
6. Support multiple variants (generate N times, save as name-1.png, name-2.png)

For style matching with a reference image, include the reference as an inlineData part before the text prompt, and use temperature 0.7 (instead of 1.0).

See references/api-pattern.md for the full implementation pattern including error handling and response parsing.

Critical: Never pass prompts via curl + bash arguments — shell escaping breaks on apostrophes. Always use Python's json.dumps() or write the prompt to a file first.

Step 4: Post-Process (Optional)

Use the image-processing skill for resizing, format conversion, or optimisation.

Step 5: Present to User

Show the generated images for review. Read the image files to display them inline if possible, otherwise describe what was generated and let the user open them.

Presets

Starting prompts — enhance with project-specific context (colours, mood, subject):

Preset	Base Prompt
hero-background	"Wide atmospheric background, soft-focus, [colour tones], [mood], landscape 1920x1080"
og-image	"Clean branded card background, [brand colours], subtle gradient, 1200x630"
placeholder-photo	"Professional stock-style photo of [subject], natural lighting, warm tones"
texture-pattern	"Subtle repeating texture, [material], seamless tile, muted [colour]"
product-shot	"Product photography, [item] on [surface], soft studio lighting, clean background"

Model Selection

Use case	Model	Cost
Drafts, quick placeholders	gemini-2.5-flash-image	Free (~500/day)
Final client assets	gemini-3-pro-image-preview	~$0.04/image
Style-matched variants	gemini-3-pro-image-preview + reference image	~$0.04/image

Verify current model IDs if errors occur — they change frequently.

Reference Files

When	Read
Building effective prompts	references/prompting-guide.md
API implementation details	references/api-pattern.md