# gpt-image
Generate and edit images with OpenAI's **gpt-image-2** model — from your terminal, or automatically from [Claude Code](https://claude.com/claude-code) via an Agent Skill.
Works with either:
- an **OpenAI API key** (pay per image), or
- your **ChatGPT subscription** (Plus/Pro/Team) via OAuth — no API key, uses your plan's quota.
This repo contains two pieces:
| Folder | What it is |
|---|---|
| [`gpt-image/`](gpt-image/) | The CLI — a zero-dependency [Bun](https://bun.sh) package |
| [`skill/`](skill/) | An Agent Skill that teaches Claude Code to use the CLI |
## Quick start
Requires [Bun](https://bun.sh) ≥ 1.0.
```bash
# Option A: API key
export OPENAI_API_KEY=sk-...
# Option B: ChatGPT subscription — sign in once in your browser
bunx gpt-image login
# (already using Codex CLI? its login is reused automatically, skip this)
# Generate
bunx gpt-image generate "a watercolor red fox in a snowy forest" -o fox.png
# Edit
bunx gpt-image edit "make the sky a dramatic sunset" -i photo.jpg -o sunset.png
# Combine reference images
bunx gpt-image edit "gift basket containing all these items" \
-i basket.png -i soap.png -i candle.png -o basket-full.png
```
> **Running from a local checkout** (not installed from npm): either run `bun link` inside `gpt-image/` once so `bunx gpt-image` resolves, or call it directly with `bun run gpt-image/src/cli.ts ...`.
## CLI options
```
gpt-image login Sign in with a ChatGPT subscription
gpt-image generate "<prompt>" -o out.png Generate from a text prompt
gpt-image edit "<prompt>" -i in.png -o out.png Edit / combine images
-o, --output <path> Output file path (required)
--size <WxH|auto> Any size: multiples of 16, ratio ≤ 3:1, max edge 3840px
--quality <q> low | medium | high | auto
-n <count> Number of images (1–10)
--format <fmt> png | jpeg | webp (API-key mode only for jpeg/webp)
--compression <0-100> jpeg/webp compression (API-key mode only)
--oauth Force ChatGPT OAuth even if OPENAI_API_KEY is set
-i, --image <path> Edit input; repeat for multiple references (first = base)
--mask <path> Alpha-channel PNG; transparent areas get edited (API-key mode only)
```
Common sizes: `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), `2048x2048`, `3840x2160`.
## Authentication details
**API key** — set `OPENAI_API_KEY` as an env var or in a `.env` file in your working directory (Bun loads it automatically). Set `OPENAI_BASE_URL` to use a proxy or any OpenAI-compatible provider. When both an API key and an OAuth session exist, the API key wins; pass `--oauth` to override.
**ChatGPT subscription** — `gpt-image login` runs the same OAuth flow as OpenAI's Codex CLI and stores tokens in `~/.config/gpt-image/auth.json` (auto-refreshed). If you already use Codex CLI, its login at `~/.codex/auth.json` is picked up automatically.
Heads-up on OAuth mode:
- It's an **unofficial route** (the same backend Codex CLI talks to) — OpenAI could change or restrict it at any time. The API key path is the stable fallback.
- Not supported by the ChatGPT backend: masks, jpeg/webp output, compression; edits are capped at 5 reference images.
## Model notes (gpt-image-2)
- No transparent backgrounds — generate on a solid color and post-process if you need a cutout.
- High-quality renders can take 30s–2min; that's normal.
- Sizes above 2560x1440 are experimental per OpenAI's docs.
## Using with Claude Code
The [`skill/`](skill/) folder is an Agent Skill: once installed, Claude Code automatically reaches for the CLI whenever you ask it to create or edit an image ("make me a logo", "restyle this screenshot", ...).
Install it with the [skills](https://github.com/vercel-labs/skills) CLI:
```bash
npx skills add egoist/gpt-image
```
(or from a local checkout: `npx skills add ./skill`)
Then just ask Claude Code for an image. Auth setup is the same as above; for API-key use inside Claude Code you can also put the key in `.claude/settings.json`:
```json
{ "env": { "OPENAI_API_KEY": "sk-..." } }
```
## License
MIT