gpt-image-2

gpt-image-2

Generate and edit images with OpenAI's gpt-image-2 model via a small zero-dependency Python script. The script calls the OpenAI Images API, decodes the returned image, saves it to disk, and prints the absolute path(s).

Prerequisites

An OpenAI API key. The script looks for it in this order:

1. the OPENAI_API_KEY environment variable, then
2. a saved key file at ~/.config/gpt-image-2/credentials.

If the script reports no key is found, run the /gpt-image-2:setup command (it walks the user through saving a key), or tell the user to export OPENAI_API_KEY=sk-.... Prefer not to have the user paste the key into chat; point them at setup or the env var instead. To save a key non-interactively: printf '%s' "$KEY" | python3 .../gpt_image.py set-key -.

When to use

• Generate (text → image): "draw a…", "create an image of…", "make a logo/icon/poster…"
• Edit (image + prompt → image): modify, restyle, inpaint, remove/add objects, change colors, or combine multiple reference images into one.

How to run

The script lives next to this file. Always invoke it with its absolute path so it works regardless of the current directory:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/gpt-image-2/gpt_image.py" <generate|edit> "<prompt>" [options]

If CLAUDE_PLUGIN_ROOT is not set, use the directory containing this SKILL.md.

Generate

python3 .../gpt_image.py generate "a watercolor red fox sleeping in snow" \
  --size 1024x1536 --quality high --out fox.png

Edit (single or multiple input images, optional mask)

# restyle / modify one image
python3 .../gpt_image.py edit "make it look like a vintage oil painting" \
  --image photo.png --out painting.png

# combine several reference images into one composition
python3 .../gpt_image.py edit "put the product from image 1 on the beach from image 2" \
  --image product.png --image beach.png --out composite.png

# inpaint: only the transparent regions of the mask are regenerated
python3 .../gpt_image.py edit "replace the sky with a starry night" \
  --image scene.png --mask sky-mask.png --out scene-night.png

Options

Option	Values	Notes
--size	WxH or auto	any size with edges a multiple of 16, max edge 3840, ratio ≤ 3:1. Common: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160 (4K). Default auto
--quality	low, medium, high, auto	higher = slower + more tokens
--background	transparent, opaque, auto	transparent needs --format png or webp
--format	png, jpeg, webp	default png
--compression	0-100	jpeg/webp only
--n	integer	number of images; multi-output files get -1, -2 suffixes
--out	path	where to save; defaults to ./gpt-image-1.<ext>
--model	model id	overrides default; or set GPT_IMAGE_MODEL env var

After running

The script prints the saved absolute path(s) to stdout (and token usage to stderr). Report the saved path to the user. If the image was saved into the working directory, show it as a clickable markdown link. If the API returns an error (quota, content policy, invalid size), surface the message verbatim rather than retrying blindly.

Notes

• For a transparent logo/icon, use --background transparent --format png.
• Generation can take 10-60s at high quality; that is normal, do not abort early.
• The model name defaults to gpt-image-2. If the API reports the model does not exist, fall back with --model gpt-image-1.