gemini-image

name	gemini-image
description	Generate images using the Google Gemini Image Generation API. Use when an agent needs to create, illustrate, or visualize anything — icons, hero images, diagrams, concept art, product shots, illustrations. Activates on "generate image", "create an image", "illustrate this", "make a picture of", "draw", or any request to produce a visual asset.
compatibility	{"tools":["run_in_terminal"],"env":["GEMINI_API_KEY"]}

Gemini Image Generation

Generates images via the Google Gemini API and saves them to disk as PNG files.

Prerequisites

• GEMINI_API_KEY environment variable set — see below if not set
• Go 1.22+ installed (go version to verify)

Setting up GEMINI_API_KEY

Before generating images, check whether the key is set:

# Check if set
echo $env:GEMINI_API_KEY   # PowerShell
echo $GEMINI_API_KEY        # bash/zsh

If it's empty or missing, prompt the user:

"To generate images, you need a Google AI Studio API key. It's free — visit https://aistudio.google.com/apikey, sign in, click Create API key, and copy it. Then set it in your terminal:"

PowerShell (current session):

$env:GEMINI_API_KEY = "your-key-here"

PowerShell (permanent, user profile):

[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-key-here", "User")

bash/zsh (add to ~/.bashrc or ~/.zshrc for persistence):

export GEMINI_API_KEY="your-key-here"

Once the user confirms the key is set, proceed with image generation.

Available scripts

• scripts/ — Image generation CLI (Go, self-contained with inline dependencies)

Usage

Run from the scripts/ directory (where go.mod lives):

cd scripts
go run . [flags] <prompt words...>

Flags

Flag	Default	Description
-o, --output FILE	auto (image-NNN.png)	Output file path
-m, --model MODEL	gemini-3.1-flash-image-preview	Gemini model
--aspect RATIO	1:1	Aspect ratio

Models

Model	Best for
gemini-3.1-flash-image-preview	Best all-round quality/speed (default)
gemini-2.5-flash-image	Fast, high-volume, lower cost
gemini-3-pro-image-preview	Professional assets, complex prompts, up to 4K

Aspect ratios

1:1 16:9 9:16 3:2 2:3 4:3 3:4 4:5 5:4 21:9

Output

• Prints the saved file path to stdout on success — capture it for use in other steps
• Progress and diagnostics go to stderr
• Exit codes: 0 success · 1 invalid args · 2 API error · 3 write error

Examples

cd scripts

# Blog hero image
go run . --aspect 16:9 --output hero.png \
  "photorealistic misty mountain range at golden hour, wide angle shot"

# Icon or sticker
go run . --aspect 1:1 --output icon.png \
  "minimalist Go gopher mascot, flat design, white background, no text"

# Portrait illustration
go run . --aspect 2:3 --output portrait.png \
  "watercolor portrait of a software engineer, warm tones, abstract background"

# Product shot
go run . -m gemini-3-pro-image-preview --aspect 3:2 --output product.png \
  "studio-lit product photograph of a ceramic coffee mug on a marble surface, three-point softbox lighting"

# Capture the output path for use in a pipeline
$imgPath = go run . "abstract dark blue tech background, geometric"

Agent workflow

1. Compose a detailed prompt — include subject, style, lighting, mood, and any text to render
2. Choose aspect ratio — match the intended use (16:9 for headers, 1:1 for icons, 9:16 for mobile)
3. cd into the skill's scripts/ directory, then run go run . capturing stdout as the file path
4. Use the returned path in subsequent steps (embed in HTML, commit to repo, attach to PR, etc.)

Prompting tips

• Describe the scene narratively, not as a keyword list — the model understands context
• For photorealistic results, use camera terms: wide-angle shot, macro, golden hour, soft bokeh
• For text in images, describe the font style: bold sans-serif, elegant serif; use gemini-3-pro-image-preview for reliable text rendering
• For icons/stickers, specify white background, no text and a clear style like flat design or 3D clay
• Iterate: run once, then refine the prompt and run again