gpt-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 ```bash bunx gpt-image generate "<prompt>" -o output.png [options] ``` Examples: ```bash # 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 ```bash 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: ```bash # 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 ...`.