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

GitHub

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

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:

  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.