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:
- 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.
- 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 ....
1---2name: gpt-image3description: 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".4---56# GPT Image (gpt-image-2)78Generate 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).910## Authentication1112The CLI supports two auth modes and picks one automatically:13141. **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`.152. **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.1617If 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.1819**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.2021Each 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.2223## Generating images2425```bash26bunx gpt-image generate "<prompt>" -o output.png [options]27```2829Examples:3031```bash32# Simple generation, model picks size/quality33bunx gpt-image generate "a watercolor red fox in snowy forest" -o fox.png3435# High-quality landscape banner36bunx gpt-image generate "minimalist hero banner for a coffee brand" \37 -o banner.png --size 1536x1024 --quality high3839# Three quick draft variations as jpeg (API-key mode)40bunx gpt-image generate "flat vector cat logo" \41 -o logo.jpg -n 3 --quality low --format jpeg42```4344## Editing images4546```bash47bunx gpt-image edit "<prompt>" -i input.png -o output.png [options]48```4950- 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").51- `--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.52- gpt-image-2 always processes input images at high fidelity; there is no `input_fidelity` parameter to set.5354Examples:5556```bash57# Restyle a photo58bunx gpt-image edit "convert to Studio Ghibli anime style" -i photo.jpg -o ghibli.png5960# Targeted edit with a mask (API-key mode)61bunx gpt-image edit "add a pink flamingo floating in the pool" \62 -i backyard.png --mask pool-mask.png -o out.png6364# Combine references65bunx gpt-image edit "gift basket containing all these items" \66 -i basket.png -i soap.png -i candle.png -o basket-full.png67```6869## Options reference (both subcommands)7071| Option | Values | Notes |72|---|---|---|73| `--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. |74| `--quality` | `low` / `medium` / `high` / `auto` (default) | low = fast drafts, high = final assets (slower, pricier) |75| `-n` | 1–10 | Number of images; multi-image outputs get `-1`, `-2`… suffixes |76| `--format` | `png` (default) / `jpeg` / `webp` | Use jpeg/webp for smaller files (API-key mode only) |77| `--compression` | 0–100 | jpeg/webp only (API-key mode) |78| `--oauth` | flag | Force ChatGPT-subscription OAuth even when `OPENAI_API_KEY` is set |7980## Model constraints to keep in mind8182- **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.83- Calls can take 30s–2min at high quality, which is normal — don't kill the process early (the CLI allows up to 10 minutes).84- The response may include a `revised_prompt` (the model's expanded interpretation), which the CLI prints — useful for iterating.8586## Workflow tips8788- 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).89- 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.90- For edits of the user's own files, never overwrite the original — always write to a new output path.91- 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 ...`.
egoist