GPT Image Skill
Generate or edit images using OpenAI's GPT Image models through a bundled Python script.
Resolve the skill directory
Before running any command, resolve the absolute directory containing this SKILL.md and refer to it as <skill-dir>. Never assume the current working directory is the Skill directory. Keep user input and output paths relative to the user's working directory unless the user requests another location.
Requirements
- OPENAI_API_KEY: Must be configured in
~/.gpt-image.env or export OPENAI_API_KEY=<your-key>
- OPENAI_API_BASE (optional): Custom API base URL for compatible endpoints (e.g. Azure OpenAI, proxies). Set in
~/.gpt-image.env or export it.
- Python3 with dependencies: openai, httpx, python-dotenv. Install via
python3 -m pip install -r "<skill-dir>/requirements.txt" if not installed yet.
- Executable:
<skill-dir>/gpt_image.py
Instructions
For image generation
Ask the user for:
- What they want to create (the prompt)
- Desired size (optional, defaults to 1024x1024)
- Output filename (optional, auto-generates UUID-based name if not specified)
- Model preference (optional, defaults to gpt-image-2)
- Quality (optional, defaults to auto)
- Number of images (optional, defaults to 1)
Run the script:
python3 "<skill-dir>/gpt_image.py" --prompt "description of image" --output "filename.png"
Show the user the saved image path when complete.
For image editing
Ask the user for:
- Input image file(s) to edit
- What changes they want (the prompt)
- Output filename (optional)
Run with input images:
python3 "<skill-dir>/gpt_image.py" edit --prompt "editing instructions" --input image1.png image2.png --output "edited.png"
Parent directories in the output path are created automatically. When --format is omitted, the script infers it from .png, .jpg/.jpeg, or .webp; otherwise it defaults to PNG.
Available Options
Models (--model)
gpt-image-2 (default) — Latest model with strong instruction following, text rendering, and broad world knowledge
gpt-image-1.5 — Mid-tier model
gpt-image-1 — First-generation GPT image model
gpt-image-1-mini — Lightweight, faster generation
Sizes (--size)
1024x1024 (default) — Square
1024x1536 — Portrait (2:3)
1536x1024 — Landscape (3:2)
auto — Let the model decide
Quality (--quality)
auto (default) — Model decides optimal quality
high — Higher detail, slower
medium — Balanced
low — Fastest
Output Format (--format)
png (default) — Lossless
jpeg — Smaller file size
webp — Modern format, good compression
Background (--background)
auto (default) — Model decides
transparent — Transparent background (png/webp only)
opaque — Solid background
Other Options
--n <count> — Number of images to generate (default: 1)
--output <filename> — Output filename (default: auto-generated)
Examples
Generate a simple image
python3 "<skill-dir>/gpt_image.py" --prompt "A serene mountain landscape at sunset with a lake"
Generate with specific size and output
python3 "<skill-dir>/gpt_image.py" \
--prompt "Modern minimalist logo for a tech startup" \
--size 1024x1024 \
--quality high \
--output "logo.png"
Generate landscape image
python3 "<skill-dir>/gpt_image.py" \
--prompt "Futuristic cityscape with flying cars" \
--size 1536x1024 \
--output "cityscape.png"
Generate with transparent background
python3 "<skill-dir>/gpt_image.py" \
--prompt "A cute cartoon cat mascot" \
--background transparent \
--format png \
--output "mascot.png"
Generate multiple images
python3 "<skill-dir>/gpt_image.py" \
--prompt "Abstract art in the style of Kandinsky" \
--n 3 \
--output "art.png"
Edit existing images
python3 "<skill-dir>/gpt_image.py" edit \
--prompt "Add a rainbow in the sky" \
--input photo.png \
--output "photo-with-rainbow.png"
Combine multiple reference images
python3 "<skill-dir>/gpt_image.py" edit \
--prompt "Create a gift basket containing all items shown" \
--input item1.png item2.png item3.png \
--output "gift-basket.png"
Use a different model
python3 "<skill-dir>/gpt_image.py" \
--prompt "Detailed portrait of a cat in watercolor style" \
--model gpt-image-1 \
--output "cat-portrait.png"
Error Handling
If the script fails:
- Check that
OPENAI_API_KEY is exported
- If using a custom endpoint, verify
OPENAI_API_BASE is correct
- Verify input image files exist and are readable (for editing)
- Ensure the output directory is writable
- Check that the model name is valid
Best Practices
- Be descriptive in prompts — include style, mood, colors, composition details
- For logos/icons, use square size (1024x1024) with transparent background
- For social media, use portrait (1024x1536) for stories or square for posts
- For wallpapers/headers, use landscape (1536x1024)
- Use
high quality for final output, auto for quick iterations
- GPT Image models excel at text rendering — include text in prompts when needed
- For editing, provide clear instructions about what to change and what to keep
1---
2name: gpt-image-skill
3description: 'Generate or edit images using OpenAI GPT Image API (gpt-image-2, gpt-image-1, etc). Triggers: "gpt image", "openai image", "generate image with openai", "draw image", "create image", "image generation", "AI drawing", "图片生成", "AI绘图", "生成图片", "画图". Use this skill whenever the user wants to generate or edit images and mentions OpenAI, GPT, or when OPENAI_API_KEY is available.'
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/gpt-image-skill
6---
7
8# GPT Image Skill
9
10Generate or edit images using OpenAI's GPT Image models through a bundled Python script.
11
12## Resolve the skill directory
13
14Before running any command, resolve the absolute directory containing this `SKILL.md` and refer to it as `<skill-dir>`. Never assume the current working directory is the Skill directory. Keep user input and output paths relative to the user's working directory unless the user requests another location.
15
16## Requirements
17
181. **OPENAI_API_KEY**: Must be configured in `~/.gpt-image.env` or `export OPENAI_API_KEY=<your-key>`
192. **OPENAI_API_BASE** (optional): Custom API base URL for compatible endpoints (e.g. Azure OpenAI, proxies). Set in `~/.gpt-image.env` or export it.
203. **Python3 with dependencies**: openai, httpx, python-dotenv. Install via `python3 -m pip install -r "<skill-dir>/requirements.txt"` if not installed yet.
214. **Executable**: `<skill-dir>/gpt_image.py`
22
23## Instructions
24
25### For image generation
26
271. Ask the user for:
28 - What they want to create (the prompt)
29 - Desired size (optional, defaults to 1024x1024)
30 - Output filename (optional, auto-generates UUID-based name if not specified)
31 - Model preference (optional, defaults to gpt-image-2)
32 - Quality (optional, defaults to auto)
33 - Number of images (optional, defaults to 1)
34
352. Run the script:
36
37 ```bash
38 python3 "<skill-dir>/gpt_image.py" --prompt "description of image" --output "filename.png"
39 ```
40
413. Show the user the saved image path when complete.
42
43### For image editing
44
451. Ask the user for:
46 - Input image file(s) to edit
47 - What changes they want (the prompt)
48 - Output filename (optional)
49
502. Run with input images:
51
52 ```bash
53 python3 "<skill-dir>/gpt_image.py" edit --prompt "editing instructions" --input image1.png image2.png --output "edited.png"
54 ```
55
56 Parent directories in the output path are created automatically. When `--format` is omitted, the script infers it from `.png`, `.jpg`/`.jpeg`, or `.webp`; otherwise it defaults to PNG.
57
58## Available Options
59
60### Models (--model)
61
62- `gpt-image-2` (default) — Latest model with strong instruction following, text rendering, and broad world knowledge
63- `gpt-image-1.5` — Mid-tier model
64- `gpt-image-1` — First-generation GPT image model
65- `gpt-image-1-mini` — Lightweight, faster generation
66
67### Sizes (--size)
68
69- `1024x1024` (default) — Square
70- `1024x1536` — Portrait (2:3)
71- `1536x1024` — Landscape (3:2)
72- `auto` — Let the model decide
73
74### Quality (--quality)
75
76- `auto` (default) — Model decides optimal quality
77- `high` — Higher detail, slower
78- `medium` — Balanced
79- `low` — Fastest
80
81### Output Format (--format)
82
83- `png` (default) — Lossless
84- `jpeg` — Smaller file size
85- `webp` — Modern format, good compression
86
87### Background (--background)
88
89- `auto` (default) — Model decides
90- `transparent` — Transparent background (png/webp only)
91- `opaque` — Solid background
92
93### Other Options
94
95- `--n <count>` — Number of images to generate (default: 1)
96- `--output <filename>` — Output filename (default: auto-generated)
97
98## Examples
99
100### Generate a simple image
101
102```bash
103python3 "<skill-dir>/gpt_image.py" --prompt "A serene mountain landscape at sunset with a lake"
104```
105
106### Generate with specific size and output
107
108```bash
109python3 "<skill-dir>/gpt_image.py" \
110 --prompt "Modern minimalist logo for a tech startup" \
111 --size 1024x1024 \
112 --quality high \
113 --output "logo.png"
114```
115
116### Generate landscape image
117
118```bash
119python3 "<skill-dir>/gpt_image.py" \
120 --prompt "Futuristic cityscape with flying cars" \
121 --size 1536x1024 \
122 --output "cityscape.png"
123```
124
125### Generate with transparent background
126
127```bash
128python3 "<skill-dir>/gpt_image.py" \
129 --prompt "A cute cartoon cat mascot" \
130 --background transparent \
131 --format png \
132 --output "mascot.png"
133```
134
135### Generate multiple images
136
137```bash
138python3 "<skill-dir>/gpt_image.py" \
139 --prompt "Abstract art in the style of Kandinsky" \
140 --n 3 \
141 --output "art.png"
142```
143
144### Edit existing images
145
146```bash
147python3 "<skill-dir>/gpt_image.py" edit \
148 --prompt "Add a rainbow in the sky" \
149 --input photo.png \
150 --output "photo-with-rainbow.png"
151```
152
153### Combine multiple reference images
154
155```bash
156python3 "<skill-dir>/gpt_image.py" edit \
157 --prompt "Create a gift basket containing all items shown" \
158 --input item1.png item2.png item3.png \
159 --output "gift-basket.png"
160```
161
162### Use a different model
163
164```bash
165python3 "<skill-dir>/gpt_image.py" \
166 --prompt "Detailed portrait of a cat in watercolor style" \
167 --model gpt-image-1 \
168 --output "cat-portrait.png"
169```
170
171## Error Handling
172
173If the script fails:
174
175- Check that `OPENAI_API_KEY` is exported
176- If using a custom endpoint, verify `OPENAI_API_BASE` is correct
177- Verify input image files exist and are readable (for editing)
178- Ensure the output directory is writable
179- Check that the model name is valid
180
181## Best Practices
182
1831. Be descriptive in prompts — include style, mood, colors, composition details
1842. For logos/icons, use square size (1024x1024) with transparent background
1853. For social media, use portrait (1024x1536) for stories or square for posts
1864. For wallpapers/headers, use landscape (1536x1024)
1875. Use `high` quality for final output, `auto` for quick iterations
1886. GPT Image models excel at text rendering — include text in prompts when needed
1897. For editing, provide clear instructions about what to change and what to keep