# Gpt Image

> 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".

- Skill: `egoist/gpt-image` (Agent Skill)
- Install (CLI): `npx skillmds@latest add egoist/gpt-image`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egoist/gpt-image/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: egoist (https://skillmd.com/u/egoist)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egoist/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 ...`.