behzadsp/claude-code-image-gen
image-gen
UnverifiedGenerate 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.
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:
{"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
-
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. -
Pick the aspect ratio from where the image will be used, not by default:
Ratio Use for 16:9Hero images, headers, slides, OG images 1:1Avatars, thumbnails, social tiles 9:16Mobile stories, vertical banners 4:3/3:2Blog body images, photo-style content -
Let the provider default unless there is a reason. Omit
--providerand the script uses the first one with credentials, preferringopenai. Pass--provideronly when the user names one or the task needs its specific strength (see the table below). -
Check the live model list before naming a model. Model names change often and a wrong one fails the call:
imagegen --provider openai --list-modelsWorks for
openaiandgemini. Other providers have no catalog endpoint — see reference.md. -
Save into the project, not a temp dir, when the image is a real asset. Default is
./generated-images/<timestamp>-<provider>.png. -
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:
# 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:
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.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |