---
name: satasuk03/gpt-image-2
source: https://app.decimal.ai/s/satasuk03-gpt-image-2@1/SKILL.md
source_sha256: d914150ec8cb
---

# gpt-image-2 — image generation & editing

Calls OpenAI's Image API with the `gpt-image-2` model (default). Switch to `gpt-image-1.5` with `--model gpt-image-1.5` when you need transparent backgrounds. Two capabilities:

- **Generate** — text → image (`scripts/generate.py`)
- **Edit** — image(s) + optional mask → image (`scripts/edit.py`)

For full parameter reference and advanced patterns (Responses API multi-turn, streaming, custom resolutions), see `references/api-reference.md` and `references/examples.md`.

## Prerequisites

1. `OPENAI_API_KEY` exported in the environment.
2. Python 3.9+ with `openai` installed. If `Pillow` is needed for mask alpha-channel fixup, install `pillow` too.
   ```bash
   pip install openai pillow
   ```
3. The OpenAI org must be **API-verified** to call GPT Image models. If a 403 mentions verification, point the user to https://platform.openai.com/settings/organization/general.

## Quickstart

### Generate
```bash
python scripts/generate.py \
  --prompt "A children's book drawing of a vet listening to a baby otter's heartbeat" \
  --output otter.png \
  --size 1024x1024 \
  --quality medium
```

### Generate with transparent background (requires `--model gpt-image-1.5`)
```bash
python scripts/generate.py \
  --model gpt-image-1.5 \
  --prompt "A shiny red apple on a transparent background" \
  --output apple.png \
  --background transparent
```

### Edit (single image, prompt-only)
```bash
python scripts/edit.py \
  --image input.png \
  --prompt "Add a small red balloon in the upper-left corner" \
  --output edited.png
```

### Edit with mask (inpainting)
```bash
python scripts/edit.py \
  --image sunlit_lounge.png \
  --mask mask.png \
  --prompt "A pool containing a flamingo" \
  --output lounge.png
```

### Edit using multiple references (composition)
```bash
python scripts/edit.py \
  --image lotion.png bath-bomb.png incense.png soap.png \
  --prompt "A photorealistic gift basket on a white background labeled 'Relax & Unwind' containing all the items in the references" \
  --output basket.png
```

## Decision rules

When the user asks to make/edit an image, follow this order:

1. **Pure text → image** → use `generate.py`.
2. **Has 1+ input images, no specific region** → use `edit.py` (the model treats them as references).
3. **Has 1 input image + a region to change** → use `edit.py` with `--mask`. The mask must:
   - Be the **same dimensions and format** as the first input image.
   - Have an **alpha channel** where transparent = "edit this area", opaque = "keep this area".
   - If the user supplies a black-and-white mask, run `scripts/edit.py --fix-mask <path>` first (auto-adds alpha) — see `references/examples.md`.

## Parameters cheat sheet

| Flag | Values | Default | Notes |
|------|--------|---------|-------|
| `--size` | `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, custom `WxH`, or `auto` | `auto` | Both edges multiples of 16; max edge 3840; ratio ≤ 3:1; total pixels in [655 360, 8 294 400] |
| `--quality` | `low`, `medium`, `high`, `auto` | `auto` | Use `low` for drafts; `medium`/`high` for final |
| `--format` | `png`, `jpeg`, `webp` | `png` | `jpeg` is fastest |
| `--compression` | 0–100 | unset | Only with `jpeg` / `webp` |
| `--n` | int ≥ 1 | 1 | Multiple images per call |
| `--moderation` | `auto`, `low` | `auto` | `low` is less restrictive |
| `--model` | `gpt-image-2`, `gpt-image-1.5` | `gpt-image-2` | `gpt-image-1.5` supports `transparent` backgrounds |
| `--background` | `auto`, `opaque`, `transparent` | `auto` | `transparent` only works with `--model gpt-image-1.5` |

## Things to know about `gpt-image-2`

- **Transparent backgrounds need `gpt-image-1.5`.** `gpt-image-2` does not support `--background transparent`; use `--model gpt-image-1.5 --background transparent` instead.
- **Always high-fidelity inputs.** The `input_fidelity` param does not apply — every reference image is processed at high fidelity (and counted as more input tokens accordingly).
- **Latency.** Complex prompts at `high` quality can take up to ~2 min. Use `low` while iterating, then re-run at `high`.
- **Cost (USD per output image, approximate):** low `1024x1024` ≈ $0.006, medium ≈ $0.053, high ≈ $0.211. Larger sizes cost more. See `references/api-reference.md` for the full table.
- **Output is base64.** Both scripts decode and write the bytes to `--output`; no manual base64 handling needed.

## When to escalate to the Responses API

The Image API (used by these scripts) is the right call for one-shot generate/edit. Switch to the Responses API instead when the user wants:

- **Multi-turn iterative editing** ("now make it realistic", "now add a hat") with conversation state via `previous_response_id`.
- **Streaming partial images** (1–3 progressive previews while the final renders).
- **Mixed text + image conversations** where the LLM decides whether to generate or edit.

`references/examples.md` has working snippets for both.