image-gen

---
name: image-gen
description: Generate images from text prompts through OpenAI (gpt-image-2.5), Google Gemini (gemini-3-pro-image), Higgsfield, Black Forest Labs FLUX, or any OpenAI-compatible endpoint such as xAI Grok or Recraft. Use when the user asks to generate, create, render, or make an image, hero image, illustration, logo concept, OG image, poster, thumbnail, or social card, when a project has placeholder images to replace, or when the user names an image model or asks which image providers are available.
---

# Image Generation

One CLI over every configured image provider. Picks the first provider whose
credentials exist, saves a PNG, prints JSON.

## Quick start

If `imagegen` is on PATH, use it from anywhere. Otherwise run `scripts/generate.py`
from this skill's base directory, which Claude Code prints when the skill loads.

```bash
imagegen \
  --prompt "Minimalist 3D illustration of floating geometric shapes, deep purple to electric blue gradient, soft glow, website header" \
  --aspect 16:9 \
  --out ./generated-images/hero.png
```

Output:
```json
{"success": true, "filePath": "/abs/path/hero.png", "provider": "openai", "model": "gpt-image-2.5-sunburst", "bytes": 1217131}
```

Errors go to stderr as `{"success": false, "error": "..."}` with exit code 1.

## Instructions

1. **Craft the prompt before calling.** Use `[Style] [Subject] [Composition] [Atmosphere]`.
   Name the palette when the image has to match an existing design. Vague prompts
   ("make it look good") waste a paid call.

2. **Pick the aspect ratio from where the image will be used**, not by default:

   | Ratio | Use for |
   |-------|---------|
   | `16:9` | Hero images, headers, slides, OG images |
   | `1:1` | Avatars, thumbnails, social tiles |
   | `9:16` | Mobile stories, vertical banners |
   | `4:3` / `3:2` | Blog body images, photo-style content |

3. **Let the provider default unless there is a reason.** Omit `--provider` and the
   script uses the first one with credentials, preferring `openai`. Pass
   `--provider` only when the user names one or the task needs its specific
   strength (see the table below).

4. **Check the live model list before naming a model.** Model names change often and
   a wrong one fails the call:
   ```bash
   imagegen --provider openai --list-models
   ```
   Works for `openai` and `gemini`. Other providers have no catalog endpoint —
   see [reference.md](reference.md).

5. **Save into the project**, not a temp dir, when the image is a real asset.
   Default is `./generated-images/<timestamp>-<provider>.png`.

6. **Show the result.** Read the saved file so the user sees it before it gets wired
   into anything.

## Providers

| Provider | Credentials | Default model | Strength |
|----------|-------------|---------------|----------|
| `openai` | `OPENAI_API_KEY` | `gpt-image-2.5-sunburst` | Accurate text in images, poster and UI work, instruction following |
| `gemini` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | `gemini-3-pro-image-preview` | Iterative editing, reference-image consistency |
| `higgsfield` | `HF_API_KEY_ID` + `HF_API_KEY_SECRET` | `soul/v2/standard` | Cinematic and editorial photography looks |
| `bfl` | `BFL_API_KEY` | `flux-pro-1.1` | Photoreal output, fast variants for drafts |
| `compat` | `COMPAT_API_KEY` + `COMPAT_BASE_URL` | none — pass `--model` | Any OpenAI-shaped endpoint: xAI Grok, Recraft, OpenRouter, fal |

Override a default model per provider with `--model`, or persistently with
`OPENAI_IMAGE_MODEL`, `GEMINI_IMAGE_MODEL`, `HIGGSFIELD_IMAGE_MODEL`,
`BFL_IMAGE_MODEL`, `COMPAT_IMAGE_MODEL`.

`higgsfield` and `bfl` are asynchronous: the script submits, polls the returned
status URL every 3s, and gives up after 300s.

## Options

```
--prompt, -p     required (except with --list-models / --selftest)
--provider       auto (default) | openai | gemini | higgsfield | bfl | compat
--model, -m      overrides the provider default
--aspect, -a     1:1 (default) | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3
--out, -o        output path; default ./generated-images/<ts>-<provider>.png
--extra          JSON merged into the request body for provider-specific options
--list-models    print the live model catalog (openai, gemini)
--selftest       offline checks, no network, no cost
```

`--extra` is the escape hatch for anything this CLI does not wrap:

```bash
# cheap draft
--extra '{"quality": "low"}'
# transparent cut-out (OpenAI; not supported by every model)
--extra '{"background": "transparent", "output_format": "png"}'
# Gemini image size
--extra '{"imageConfig": {"imageSize": "2K"}}'
```

## Keys

Keys exported in `~/.zshrc` are invisible to non-interactive shells and to MCP
servers. The script works around this by reading `~/.zshrc` directly as a
fallback, but the real fix is to move the export to `~/.zshenv`, which every
shell reads:

```bash
echo 'export OPENAI_API_KEY=...' >> ~/.zshenv
```

## Cost

Every call except `--selftest` and `--list-models` is billed by the provider.
Generate one image, show it, then iterate — do not fan out variations unless the
user asks for them. For drafts, prefer a cheap tier (`--extra '{"quality":"low"}'`
on OpenAI, a `flash`/`turbo`/`schnell` model elsewhere) and regenerate at full
quality once the prompt is right.

## Requirements

Python 3.8+. Standard library only — no `pip install`.

Optional: put the CLI on PATH so it runs from any directory.

```bash
ln -s "$PWD/scripts/generate.py" ~/.local/bin/imagegen
```

## Verification status

Only OpenAI was tested against a live API from this machine. Gemini, Higgsfield,
BFL and `compat` are built from published documentation and have not been run
with real credentials. Their request shapes and default model names may need
adjusting on first use; per-provider docs and raw curl equivalents are in
[reference.md](reference.md).