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:

```bash
# 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):**
> ```powershell
> $env:GEMINI_API_KEY = "your-key-here"
> ```
>
> **PowerShell (permanent, user profile):**
> ```powershell
> [System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-key-here", "User")
> ```
>
> **bash/zsh (add to ~/.bashrc or ~/.zshrc for persistence):**
> ```bash
> 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):

```bash
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

```bash
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