gpt-image

name

gpt-image

description

Generate or edit images with OpenAI's gpt-image-2 model via the gpt-image CLI. Use this skill whenever the user wants to create any kind of image — artwork, illustrations, logos, icons, photos, banners, diagrams-as-art, wallpapers, product mockups — or wants to edit, retouch, restyle, combine, or add/remove things from an existing image, even if they don't name the model. Trigger on phrases like "generate an image", "make a picture of", "draw", "create a logo", "edit this photo", "remove the background object", "change the style of this image".

GPT Image (gpt-image-2)

Generate and edit images with OpenAI's gpt-image-2 model using the gpt-image CLI, invoked as bunx gpt-image ... (requires Bun; bunx fetches the package automatically).

Authentication

The CLI supports two auth modes and picks one automatically:

1. API key (preferred when present): OPENAI_API_KEY env var — Bun also auto-loads a .env file from the working directory. Bills per image (~$0.01–0.25). Custom endpoints (proxies, OpenAI-compatible providers): set OPENAI_BASE_URL; defaults to https://api.openai.com/v1.
2. ChatGPT subscription (OAuth): uses the user's ChatGPT plan quota instead of API billing. Tokens come from a prior bunx gpt-image login (saved to ~/.config/gpt-image/auth.json) or an existing Codex CLI login (~/.codex/auth.json). Tokens auto-refresh.

If neither is configured, the CLI exits with a clear error listing both options — relay it and let the user choose. The login command opens a browser for the user to sign in themselves; never run it unprompted, and pass --oauth on generate/edit to force OAuth when an API key is also set.

OAuth mode limitations (the ChatGPT backend doesn't support these — the CLI rejects them with a clear error): --mask, --format jpeg/webp, --compression; at most 5 reference images on edits. It's also an unofficial route (the same one Codex CLI uses) and could stop working if OpenAI changes it — if OAuth requests start failing with odd errors, suggest the API-key mode.

Each image costs real money or plan quota, so default to a single image at auto quality unless the user asks for drafts (use --quality low) or final assets (use --quality high), and don't silently regenerate many variations.

Generating images

bunx gpt-image generate "<prompt>" -o output.png [options]

Examples:

# Simple generation, model picks size/quality
bunx gpt-image generate "a watercolor red fox in snowy forest" -o fox.png

# High-quality landscape banner
bunx gpt-image generate "minimalist hero banner for a coffee brand" \
  -o banner.png --size 1536x1024 --quality high

# Three quick draft variations as jpeg (API-key mode)
bunx gpt-image generate "flat vector cat logo" \
  -o logo.jpg -n 3 --quality low --format jpeg

Editing images

bunx gpt-image edit "<prompt>" -i input.png -o output.png [options]

• Repeat -i to pass multiple reference images; the first is the base image, later ones serve as references the prompt can mention ("put the logo from the second image on the mug").
• --mask mask.png restricts edits (API-key mode only): the mask must be a PNG with an alpha channel, same dimensions as the base image; transparent areas are the ones to be edited. Masking is guidance-based — the model may not follow the exact shape, so also describe the region in the prompt.
• gpt-image-2 always processes input images at high fidelity; there is no input_fidelity parameter to set.

Examples:

# Restyle a photo
bunx gpt-image edit "convert to Studio Ghibli anime style" -i photo.jpg -o ghibli.png

# Targeted edit with a mask (API-key mode)
bunx gpt-image edit "add a pink flamingo floating in the pool" \
  -i backyard.png --mask pool-mask.png -o out.png

# Combine references
bunx gpt-image edit "gift basket containing all these items" \
  -i basket.png -i soap.png -i candle.png -o basket-full.png

Options reference (both subcommands)

Option	Values	Notes
--size	WIDTHxHEIGHT or auto (default)	Arbitrary sizes: both dimensions multiples of 16, max edge 3840px, aspect ratio at most 3:1, total pixels between 655,360 and 8,294,400. Common: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160. Outputs above 2560x1440 are experimental.
--quality	low / medium / high / auto (default)	low = fast drafts, high = final assets (slower, pricier)
-n	1–10	Number of images; multi-image outputs get -1, -2… suffixes
--format	png (default) / jpeg / webp	Use jpeg/webp for smaller files (API-key mode only)
--compression	0–100	jpeg/webp only (API-key mode)
--oauth	flag	Force ChatGPT-subscription OAuth even when OPENAI_API_KEY is set

Model constraints to keep in mind

• No transparent backgrounds — gpt-image-2 does not support them. If the user needs transparency (e.g. a logo cutout), generate on a plain solid background and tell them the limitation, or offer to post-process.
• Calls can take 30s–2min at high quality, which is normal — don't kill the process early (the CLI allows up to 10 minutes).
• The response may include a revised_prompt (the model's expanded interpretation), which the CLI prints — useful for iterating.

Workflow tips

• Write prompts with concrete visual language: subject, style/medium, composition, lighting, color palette, and any text to render (put exact text in quotes; text rendering is improved but still imperfect).
• After generating, view the result yourself with the Read tool (it renders images) and confirm it matches the request before declaring success; offer one targeted revision pass if something is off.
• For edits of the user's own files, never overwrite the original — always write to a new output path.
• If bunx gpt-image fails because the package isn't published/installed, run it from a local checkout instead: bun run <repo>/gpt-image/src/cli.ts ....