Image generation — gpt-image-2

scripts/img.py wraps OpenAI's image API. Python stdlib only, nothing to install. Default model gpt-image-2; OpenAI now recommends the GPT Image 2.5 models for new work (--model gpt-image-2.5-flare, or set IMG_MODEL) — same per-token price, plus xhigh and max quality. Try one on a draft before switching a whole project.

Key: OPENAI_API_KEY, from the environment or ~/.config/marketing-agent-kit/.env. Setup: connections/openai-images-api.md, or run the connect skill.

IMG="python3 ${CLAUDE_SKILL_DIR}/scripts/img.py"
$IMG "a watercolor cat on a windowsill" -q low -o drafts/cat.png
$IMG edit "make it nighttime" -i photo.png -o out.png
$IMG edit "fill the masked area with sky" -i photo.png -m mask.png -o out.png
$IMG edit "compose these two into one scene" -i a.png -i b.png -o combined.png

img.py <prompt> without a subcommand means generate.

Quality is the main cost lever

The default is high. Quality changes the price roughly 35×, so downgrade on purpose for exploration. Approximate prices for 1024×1024 (OpenAI pricing, autumn 2026; landscape 1536×1024 is slightly cheaper):

Rule: more than three images of one concept for the user to pick from → low or medium. Re-render the chosen one at high. Say it out loud: "Rendering 4 drafts at low quality — pick one and I'll re-render it at high."

Flags

• -o PATH — output file (default img-<timestamp>.png in the current folder). With -n > 1: name-1.png, name-2.png, …
• -s SIZE — auto (default) | 1024x1024 | 1536x1024 (landscape) | 1024x1536 (portrait) | other sizes: edges in multiples of 16, up to 3840 px, aspect ratio up to 3:1 (above 2560×1440 is experimental).
• -f png|jpeg|webp, --compression 0-100 (jpeg / webp only).
• -n N — variants in one call.
• --background opaque|transparent|auto — for a transparent PNG use a GPT Image 2.5 model: --model gpt-image-2.5-flare --background transparent -f png. gpt-image-2 rejects transparent with HTTP 400 (tested 2026-10-01, although the API reference calls it a preview).
• --moderation low|auto — low only when the user asks and the content is benign.
• --model — default gpt-image-2; pin a dated snapshot when the user needs reproducibility.

Edits: without -m the whole image is rewritten from the prompt and inputs. With -m mask.png only the transparent area of the mask changes (the mask needs an alpha channel and the same size and format as the input, under 50 MB).

New OpenAI accounts may need API Organization Verification before GPT Image models work, and the lowest usage tier is limited to about 5 images per minute. Several -i flags compose several references into one image.

Art direction rules for marketing images

Read references/art-direction.md before writing a prompt for anything that will be published. The core:

• The picture illustrates the actual content, literally. A generic flat-lay of blurred papers next to a list of bonuses is filler; the same documents with their real short titles on them is an illustration.
• At most two pieces of text in an image, short ones, and check every letter of every rendered word before showing it. Misspelled text in a generated image is the most common reason it gets rejected.
• A metaphor has to be literally true to what the copy says. If it isn't, use the product itself.

After generating

• Print the absolute output path.
• If the project keeps images in a folder (assets/, public/images/), generate there.
• Look at the result yourself before presenting it: text spelling, extra fingers, cut-off objects, wrong brand colours.

Adapt it

• Add your brand to references/art-direction.md: palette (hex codes), what your product UI looks like, two or three reference images you like and why. Prompts that quote these come out on-brand.