Gemini Image Generation

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chirag2653
• Source: chirag2653/free-ai-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.