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
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
# 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 mappingindex.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
1---2name: openai-image-edit3description: Edit images via OpenAI gpt-image-1 API. Creates edited or extended images from source images and a prompt. Supports masks for selective editing, multiple input images for compositing, and input fidelity control for preserving facial features. Use when user wants to modify existing images, combine multiple images, remove/replace objects, extend images, or needs AI-powered image editing with reference images.4---5
6# OpenAI Image Edit (gpt-image-1)
7
8Edit or extend images using OpenAI's gpt-image-1 model with full API parameter support.
9
10## Workflow
11
12### 1. Gather Requirements
13
14Ask clarifying questions **one at a time** when needed:
15
16| If unclear... | Ask about |
17|---------------|-----------|
18| Which image(s) to edit | "Which image file(s) should I edit?" |
19| Edit description vague | "What specific changes do you want?" |
20| Selective edit needed | "Do you have a mask, or should I edit the whole image?" |
21| Portrait/face editing | "Want high fidelity to preserve facial features?" |
22| Multiple images | "Are these separate edits, or should I combine the images?" |
23
24**Skip questions when context is clear.**
25
26### 2. Edit
27
28```bash
29python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
30 --image <path> \
31 --prompt "description of edit"
32```
33
34### 3. Show Results
35
36After editing, show the output path and offer to open the gallery.
37
38## Setup
39
40Requires `OPENAI_API_KEY` environment variable.
41
42## Parameters
43
44| Flag | Values | Default | Description |
45|------|--------|---------|-------------|
46| `--image` | path | required | Input image (repeatable, up to 16) |
47| `--prompt` | text | required | Description of desired edit |
48| `--mask` | path | none | PNG mask (transparent = edit area) |
49| `--count` | int | 1 | Number of variations |
50| `--size` | `1024x1024`, `1536x1024`, `1024x1536`, `auto` | auto | Output dimensions |
51| `--quality` | `low`, `medium`, `high`, `auto` | high | Quality level |
52| `--background` | `transparent`, `opaque`, `auto` | API default | Background type |
53| `--format` | `png`, `jpeg`, `webp` | png | Output format |
54| `--compression` | 0-100 | API default | Compression (jpeg/webp only) |
55| `--input-fidelity` | `low`, `high` | low | Match input style/features closely |
56| `--out-dir` | path | auto | Output directory |
57| `--dry-run` | flag | - | Print request details without API call |
58
59## Examples
60
61```bash
62# Simple edit
63python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
64 --image photo.png \
65 --prompt "Add a red hat to the person"
66
67# Combine multiple images into one
68python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
69 --image lotion.png \
70 --image soap.png \
71 --image candle.png \
72 --prompt "Arrange these items in an elegant gift basket"
73
74# Use mask for selective editing (transparent areas = edit region)
75python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
76 --image landscape.png \
77 --mask sky-mask.png \
78 --prompt "Replace with dramatic sunset sky"
79
80# High fidelity for portraits (preserves facial features)
81python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
82 --image portrait.jpg \
83 --prompt "Add professional studio lighting" \
84 --input-fidelity high
85
86# Multiple variations
87python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
88 --image room.png \
89 --prompt "Redecorate in mid-century modern style" \
90 --count 4
91
92# Transparent background output
93python3 ~/.dotfiles/agents/skills/openai-image-edit/scripts/edit.py \
94 --image product.png \
95 --prompt "Remove background, keep product only" \
96 --background transparent
97```
98
99## Use Cases
100
101- **Object removal/replacement**: Remove unwanted elements, replace objects
102- **Style transfer**: Change lighting, atmosphere, artistic style
103- **Image compositing**: Combine multiple images into one scene
104- **Background editing**: Remove, replace, or extend backgrounds
105- **Portrait retouching**: Adjust lighting, add accessories (use `--input-fidelity high`)
106- **Product photography**: Clean up, relight, or recompose product shots
107
108## Output
109
110- Edited image files (`edited-*.png/jpg/webp`)
111- Input image copies (`input-*.ext`) for reference
112- `metadata.json` — edit parameters and file mapping
113- `index.html` — visual gallery showing inputs and results
114
115Output goes to `~/Projects/tmp/openai-image-edit-{timestamp}/` if that directory exists, otherwise `./tmp/`.
116
117## Masks
118
119Masks define which areas to edit:
120- **Transparent areas** (alpha = 0): Will be edited
121- **Opaque areas**: Will be preserved
122- Must be PNG format
123- Should match input image dimensions
124- Applied to the first image when using multiple inputs
majiayu000