name

gemini-image-generation

description

Generate professional images using Google's Gemini 3 Pro or Gemini 2.5 Flash image models with AI-powered prompt enhancement. Universal Python script works on all platforms. Supports custom aspect ratios (1:1, 16:9, 9:16), resolutions (1K-4K), reference images, and Google Search grounding. Activate when user says "Generate an image with Gemini", "Create using Gemini Pro/Flash", "Use Gemini to make [image]", or any image generation request mentioning Gemini/Imagen.

Gemini Image Generation

Generate images using Google's Gemini API with an interactive, AI-guided workflow.

Executing the Script

When this skill loads, your agent platform provides the skill's base directory path. Run the script relative to that path:

python scripts/generate-image.py \
    --prompt "your prompt" \
    --output "output.png" \
    --aspect-ratio "16:9" \
    --size "1K" \
    --model "gemini-3-pro-image-preview"

API Key: The script reads GEMINI_API_KEY from (in order): --env-file flag, environment variable, .env.local, .env, ~/.env.local, ~/.env

Available Models

Model	ID	Quality	Speed	Aspect/Size Control
Gemini 3 Pro	`gemini-3-pro-image-preview`	Professional	Slower	Yes
Gemini 2.5 Flash	`gemini-2.5-flash-image`	Good	Faster	No (uses defaults)

Workflow

STEP 0: Smart Extraction

Before asking questions, extract from the user's request:

Element	Patterns	Example
Prompt	Descriptive text	"sunset over mountains"
Aspect Ratio	`16:9`, `1:1`, `square`, `portrait`	"16:9"
Output Path	`.png` paths, "save to"	"save to logo.png"
Resolution	`1K`, `2K`, `4K`, `HD`	"4K"
Model	`Pro`, `Flash`	"Flash"

Smart Defaults:

Aspect: 1:1 (logos/icons → 1:1, banners → 16:9, stories → 9:16)
Size: 1K (high quality requests → 2K or 4K)
Model: ALWAYS ASK (cost implications)
Output: {sanitized-prompt}.png in project root

STEP 1: Check API Key

grep -q "GEMINI_API_KEY" .env.local 2>/dev/null || grep -q "GEMINI_API_KEY" .env 2>/dev/null

If missing: Guide user to https://aistudio.google.com/ to get a free key, then create .env.local:

GEMINI_API_KEY=your-key-here

STEP 2: Gather Missing Information

2a. Prompt (if missing): Ask "What image would you like to generate?"

2b. Prompt Enhancement (always offer):

"Would you like me to enhance this prompt using Google's Imagen best practices?"

If yes, read references/PROMPT_ENHANCEMENT.md and apply techniques:

Add hyper-specific details (colors, textures, materials)
Include camera angle/perspective (wide-angle, macro, low-angle)
Specify lighting and mood (golden hour, dramatic, cinematic)
Add artistic style if appropriate

Show before/after, get approval.

2c. Model Choice (if missing): Always ask - users must control cost:

"Pro (higher quality, more control) or Flash (faster, lower cost)?"

STEP 3: Final Confirmation

✅ Ready to generate:

📝 Prompt: [prompt]
📐 Aspect ratio: [ratio]
📊 Resolution: [size]
🤖 Model: [model]
💾 Output: [path]

Generate now, or change anything?

Allow adjustments until user confirms.

STEP 4: Execute

python scripts/generate-image.py \
    --prompt "$PROMPT" \
    --output "$OUTPUT_PATH" \
    --aspect-ratio "$ASPECT_RATIO" \
    --size "$SIZE" \
    --model "$MODEL"

STEP 5: Handle Results

Success: Report file path and size.

Errors:

GEMINI_API_KEY not found → Guide to STEP 1
HTTP 401 → Invalid key, verify at aistudio.google.com
HTTP 429 → Rate limit, wait and retry
HTTP 400 → Invalid parameters, help choose valid options

Parameter Reference

Aspect Ratios

Ratio	Use Case
`1:1`	Logos, icons, profile pics
`16:9`	YouTube banners, presentations
`9:16`	Stories, Reels, TikTok
`3:2` / `2:3`	Photos, posters
`4:3` / `3:4`	Standard displays
`4:5` / `5:4`	Instagram
`21:9`	Ultrawide cinematic

Resolutions

Size	Resolution	Use
`1K`	~1024px	Web, thumbnails
`2K`	~2048px	High-quality web, social
`4K`	~4096px	Print, HD displays

Advanced Features

Reference Images

python scripts/generate-image.py \
    --prompt "$PROMPT" \
    --output "$OUTPUT" \
    --reference "style1.png" \
    --reference "style2.png"

Max 14 references. Formats: PNG, JPEG, GIF, WebP.

Google Search Grounding

For factually accurate images (landmarks, historical figures):

python scripts/generate-image.py \
    --prompt "$PROMPT" \
    --output "$OUTPUT" \
    --grounding true

Best Practices

DO:

Parse request before asking questions (STEP 0)
Always ask about model choice (cost control)
Offer prompt enhancement
Show final confirmation before generating
Use relative path: scripts/generate-image.py

DON'T:

Skip model choice (users control cost)
Change core subject during enhancement
Skip final confirmation
Use absolute paths

References

Prompt Enhancement: See references/PROMPT_ENHANCEMENT.md for detailed techniques
Example Flows: See references/examples.md for conversation patterns