gpt-image-2
Generate and edit images with OpenAI's gpt-image-2 model. Use when the user asks to create, generate, render, edit, modify, inpaint, or composite images via OpenAI / GPT Image. Supports text-to-image
SKILL.mdgpt-image-2/SKILL.md
GitHubgpt-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
OPENAI_API_KEYexported in the environment.- Python 3.9+ with
openaiinstalled. IfPillowis needed for mask alpha-channel fixup, installpillowtoo.pip install openai pillow - 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
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)
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)
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)
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)
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:
- Pure text → image → use
generate.py. - Has 1+ input images, no specific region → use
edit.py(the model treats them as references). - Has 1 input image + a region to change → use
edit.pywith--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) — seereferences/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-2does not support--background transparent; use--model gpt-image-1.5 --background transparentinstead. - Always high-fidelity inputs. The
input_fidelityparam does not apply — every reference image is processed at high fidelity (and counted as more input tokens accordingly). - Latency. Complex prompts at
highquality can take up to ~2 min. Uselowwhile iterating, then re-run athigh. - Cost (USD per output image, approximate): low
1024x1024≈ $0.006, medium ≈ $0.053, high ≈ $0.211. Larger sizes cost more. Seereferences/api-reference.mdfor 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.