claude-code-image-gen

A Claude Code skill that generates images
through OpenAI, Google Gemini, Higgsfield, Black Forest Labs FLUX, or any
OpenAI-compatible endpoint — behind a single CLI with no dependencies.

Ask Claude for a hero image and it picks the provider you have keys for, writes
the prompt, saves the PNG into your project, and shows it to you.

you  ▸ generate a hero image for the pricing page, dark, abstract, 16:9

        ↳ skill: image-gen
        ↳ python3 scripts/generate.py -p "..." -a 16:9 -o ./public/hero.png
        ↳ {"success": true, "provider": "openai", "model": "gpt-image-2.5-sunburst"}

Why

Most image-gen integrations pin one provider, or one model name that goes stale
the next time the provider ships. This one routes across providers, reads the
live model catalog instead of a hardcoded list, and degrades to a clear error
instead of a wrong guess.

• No dependencies. Python 3.8+ standard library. No pip install, no Node,
  no MCP server to keep running.
• Provider-agnostic. Five backends, one flag. Anything OpenAI-shaped works
  without new code.
• Resilient parsing. The response walker finds a base64 blob or image URL
  anywhere in the payload, so a provider tweaking its schema does not break it.
• Async handled. Higgsfield and FLUX submit-then-poll jobs are wrapped;
  you just get a file path back.

Install

git clone https://github.com/behzadsp/claude-code-image-gen.git ~/.claude/skills/image-gen

Claude Code loads skills from ~/.claude/skills/ (personal) or .claude/skills/
(per-project, committed to git). To keep the repo elsewhere while still having it
discovered, clone where you like and symlink instead:

git clone https://github.com/behzadsp/claude-code-image-gen.git ~/src/image-gen
ln -s ~/src/image-gen ~/.claude/skills/image-gen

Restart Claude Code, then ask it for an image.

Optionally put the CLI on PATH so it also works as a plain command from any
directory:

ln -s ~/.claude/skills/image-gen/scripts/generate.py ~/.local/bin/imagegen
imagegen --selftest

Keys

Set at least one:

export OPENAI_API_KEY=sk-...              # OpenAI
export GEMINI_API_KEY=...                 # Google Gemini
export BFL_API_KEY=...                    # Black Forest Labs FLUX
export HF_API_KEY_ID=... HF_API_KEY_SECRET=...   # Higgsfield
export COMPAT_BASE_URL=... COMPAT_API_KEY=...    # anything OpenAI-shaped

Put these in ~/.zshenv, not ~/.zshrc. Non-interactive shells — which is what
agents and MCP servers run in — never read ~/.zshrc, so a key that works in
your terminal can still be invisible to tooling. The script falls back to reading
~/.zshrc directly so it works either way, but ~/.zshenv is the real fix.

Usage

The skill runs this for you, but it is a normal CLI:

python3 scripts/generate.py \
  --prompt "Minimalist 3D illustration of floating geometric shapes, deep purple to electric blue gradient, soft glow" \
  --aspect 16:9 \
  --out ./generated-images/hero.png

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

Failures print {"success": false, "error": "..."} to stderr and exit 1, with
the provider's own message passed through.

Options

auto picks the first provider whose credentials are present, preferring OpenAI.

Providers

Pin a model per provider with OPENAI_IMAGE_MODEL, GEMINI_IMAGE_MODEL,
HIGGSFIELD_IMAGE_MODEL, BFL_IMAGE_MODEL, COMPAT_IMAGE_MODEL.

Model names move fast. Check what your account can actually reach:

imagegen --provider openai --list-models   # or: python3 scripts/generate.py ...

Provider-specific options

--extra merges raw JSON into the request body, so anything the CLI does not
wrap is still reachable:

--extra '{"quality": "low"}'                               # cheap OpenAI draft
--extra '{"background": "transparent", "output_format": "png"}'  # cut-out
--extra '{"imageConfig": {"imageSize": "2K"}}'             # Gemini size

Verification status

Be aware of what has and has not been run against a live API.

The unverified backends may need their request shape or default model adjusted on
first real use. They fail loudly with the provider's own error text rather than
silently producing nothing, and the response parser is deliberately schema-tolerant
to absorb small differences. Reports and fixes from anyone with keys for these are
the most useful contribution this repo can get.

Cost

Every call except --selftest and --list-models is billed by the provider.
The skill instructs Claude to generate one image and show it rather than fanning
out variations unprompted, and to draft at a cheap quality tier before
regenerating at full quality. Budget accordingly if you wire this into anything
automated.

Adding a provider

1. Add credentials and a default model to PROVIDERS in scripts/generate.py.
2. Write a pure build_<name>() payload function so --selftest can cover it.
3. Write call_<name>(). For async APIs, return _poll(status_url, headers).
4. Register it in DISPATCH.
5. Add assertions to selftest() and run python3 scripts/generate.py --selftest.

harvest() usually means you write no result-parsing code at all — it already
finds base64 under the common keys, then falls back to URL matching.

Per-provider endpoints, payloads, and raw curl equivalents are in
reference.md.

Repo layout

SKILL.md              Skill definition — what Claude reads
reference.md          Per-provider API details and curl equivalents
scripts/generate.py   The CLI (stdlib only)

License

MIT. See LICENSE.