OpenAI Image Edit (gpt-image-1)

Edit or extend images using OpenAI's gpt-image-1 model with full API parameter support.

Workflow

1. Gather Requirements

Ask clarifying questions one at a time when needed:

If unclear...	Ask about
Which image(s) to edit	"Which image file(s) should I edit?"
Edit description vague	"What specific changes do you want?"
Selective edit needed	"Do you have a mask, or should I edit the whole image?"
Portrait/face editing	"Want high fidelity to preserve facial features?"
Multiple images	"Are these separate edits, or should I combine the images?"

Skip questions when context is clear.

2. Edit

bash

python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image <path> \
  --prompt "description of edit"

3. Show Results

After editing, show the output path and offer to open the gallery.

Setup

Requires OPENAI_API_KEY environment variable.

Parameters

Flag	Values	Default	Description
`--image`	path	required	Input image (repeatable, up to 16)
`--prompt`	text	required	Description of desired edit
`--mask`	path	none	PNG mask (transparent = edit area)
`--count`	int	1	Number of variations
`--size`	`1024x1024`, `1536x1024`, `1024x1536`, `auto`	auto	Output dimensions
`--quality`	`low`, `medium`, `high`, `auto`	high	Quality level
`--background`	`transparent`, `opaque`, `auto`	API default	Background type
`--format`	`png`, `jpeg`, `webp`	png	Output format
`--compression`	0-100	API default	Compression (jpeg/webp only)
`--input-fidelity`	`low`, `high`	low	Match input style/features closely
`--out-dir`	path	auto	Output directory
`--dry-run`	flag	-	Print request details without API call

Examples

bash

# Simple edit
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image photo.png \
  --prompt "Add a red hat to the person"

# Combine multiple images into one
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image lotion.png \
  --image soap.png \
  --image candle.png \
  --prompt "Arrange these items in an elegant gift basket"

# Use mask for selective editing (transparent areas = edit region)
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image landscape.png \
  --mask sky-mask.png \
  --prompt "Replace with dramatic sunset sky"

# High fidelity for portraits (preserves facial features)
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image portrait.jpg \
  --prompt "Add professional studio lighting" \
  --input-fidelity high

# Multiple variations
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image room.png \
  --prompt "Redecorate in mid-century modern style" \
  --count 4

# Transparent background output
python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
  --image product.png \
  --prompt "Remove background, keep product only" \
  --background transparent

Use Cases

Object removal/replacement: Remove unwanted elements, replace objects
Style transfer: Change lighting, atmosphere, artistic style
Image compositing: Combine multiple images into one scene
Background editing: Remove, replace, or extend backgrounds
Portrait retouching: Adjust lighting, add accessories (use --input-fidelity high)
Product photography: Clean up, relight, or recompose product shots

Output

Edited image files (edited-*.png/jpg/webp)
Input image copies (input-*.ext) for reference
metadata.json — edit parameters and file mapping
index.html — visual gallery showing inputs and results

Output goes to ~/Projects/tmp/openai-image-edit-{timestamp}/ if that directory exists, otherwise ./tmp/.

Masks

Masks define which areas to edit:

Transparent areas (alpha = 0): Will be edited
Opaque areas: Will be preserved
Must be PNG format
Should match input image dimensions
Applied to the first image when using multiple inputs

Search AI Tools

openai-image-edit

Install this agent skill to your Project

SKILL.md