Skip to content

behzadsp/claude-code-image-gen

image-gen

Unverified

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.

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

  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:

    RatioUse 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
  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:

    imagegen --provider openai --list-models
    

    Works for openai and gemini. Other providers have no catalog endpoint — see 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

ProviderCredentialsDefault modelStrength
openaiOPENAI_API_KEYgpt-image-2.5-sunburstAccurate text in images, poster and UI work, instruction following
geminiGEMINI_API_KEY or GOOGLE_API_KEYgemini-3-pro-image-previewIterative editing, reference-image consistency
higgsfieldHF_API_KEY_ID + HF_API_KEY_SECRETsoul/v2/standardCinematic and editorial photography looks
bflBFL_API_KEYflux-pro-1.1Photoreal output, fast variants for drafts
compatCOMPAT_API_KEY + COMPAT_BASE_URLnone — pass --modelAny 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.

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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall