Peteroooooooo/imagegen

What does imagegen do?

One command that calls /images/generations or /images/edits and saves the result into the current project.

Setup (once, by the user)

• Needs an API key for the OpenAI Images API or any OpenAI-compatible image API.
• Environment variables (on Windows, values set with setx are read from the registry, so a restart of the agent is not needed):
  • IMAGEGEN_API_KEY: the API key. Falls back to OPENAI_API_KEY.
  • IMAGEGEN_BASE_URL: optional, default https://api.openai.com/v1.
  • IMAGEGEN_MODEL: optional, default gpt-image-2.
• Python 3.8+, standard library only. Install this folder as ~/.claude/skills/imagegen/ (Claude Code) and/or ~/.codex/skills/imagegen/ (Codex).
• Optional: put an imagegen wrapper on PATH (examples in the repo's wrappers/). Without it, replace imagegen below with python <this skill folder>/scripts/imagegen.py.

Generate

imagegen "<prompt>" [--size 1536x1024] [--quality high] [--n 2] [--out path.png]

Output options (sent only when given; not every API or model accepts them): --background transparent|opaque|auto, --format png|jpeg|webp, --compression 0-100 (jpeg/webp only).

Edit (pass one or more input images)

imagegen "<what to change>" --image input.png [--image ref.png] [--mask mask.png]

Output

One JSON line on stdout:

{"ok": true, "mode": "generate", "paths": ["/path/to/project/output/imagegen/20260101-120000-orange-cat.png"], "seconds": 42.9, "model": "gpt-image-2", "revised_prompt": null, "sidecars": ["/path/to/project/output/imagegen/20260101-120000-orange-cat.json"]}

Each image gets a sidecar <same name>.json with the prompt, revised prompt, model, size, quality, other options, input image and mask paths, seconds and creation time (--no-sidecar turns it off). The last image is the last path in your previous output; if you do not have it (new session), take the newest image in output/imagegen/ and read its .json for the prompt it was made from.

On failure: {"ok": false, "error": "..."} and exit code 1. Read paths and report them to the user. If the error says there is no API key, tell the user how to set IMAGEGEN_API_KEY; do not look for keys yourself.

How to work

• Default: generate once from the user's request and report the paths. Do not open or judge the image, and do not regenerate, unless the user asks.
• Use only what the user has said. Do not invent style or details. If something without which the image is unusable is missing (exact text on the image, landscape or portrait), ask once before generating.
• When the user asks to change a result ("make the left one blue"), edit the last image with --image <last path> instead of generating from scratch.
• Several independent images can be requested in parallel (separate commands at the same time).
• Only when the user asks to iterate ("iterate until good") and you can view images: write a short checklist of checkable requirements, generate, open the image, check each item. Fix local problems with --image edits and regenerate only if the overall direction is wrong. Stop when every item passes or after 3 rounds, and report each version's path and any items that still fail.

Notes

• Without --out, files go to output/imagegen/<time>-<words>.png under the current directory (the extension follows --format).
• Sizes: 1024x1024 (square), 1536x1024 (landscape), 1024x1536 (portrait). gpt-image-2 also accepts custom sizes such as 2048x1152 (16:9): both sides multiples of 16, longest side at most 3840, aspect ratio between 1:3 and 3:1. Omit --size for auto.
• --quality low is fastest for drafts; high for final assets. xhigh / max work only on models that support them.
• One image takes about 30-90 s. Run it in the foreground with a timeout of at least 600000 ms; do not poll.
• Write prompts as: asset type, subject, style, composition, lighting, exact text in quotes if any. Non-English prompts work.
• Text that must appear on the image goes in quotes, word for word, with where it goes: headline at the top reading "Summer Sale". Spell unusual words letter by letter.
• With several input images, say what each one is for, by order: "Image 1: the product photo to edit. Image 2: style reference only."
• In edits, say exactly what changes and that everything else stays the same: "Change only the jacket to red; keep the face, pose, background and lighting unchanged." Repeat the unchanged parts in each follow-up edit.
• --background transparent needs png or webp output and a model that supports it.
• --dry-run prints the request without calling the API.
• Never print or write the API key.