GPT Image Skill
Generate or edit images using OpenAI's GPT Image models through a bundled Python script.
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, Pillow. Install via
python3 -m pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt if not installed yet.
- Executable:
${CLAUDE_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 ${CLAUDE_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 (up to 3)
- What changes they want (the prompt)
- Output filename (optional)
Run with input images:
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit --prompt "editing instructions" --input image1.png image2.png --output "edited.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 ${CLAUDE_SKILL_DIR}/gpt_image.py --prompt "A serene mountain landscape at sunset with a lake"
Generate with specific size and output
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Modern minimalist logo for a tech startup" \
--size 1024x1024 \
--quality high \
--output "logo.png"
Generate landscape image
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Futuristic cityscape with flying cars" \
--size 1536x1024 \
--output "cityscape.png"
Generate with transparent background
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "A cute cartoon cat mascot" \
--background transparent \
--format png \
--output "mascot.png"
Generate multiple images
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Abstract art in the style of Kandinsky" \
--n 3 \
--output "art.png"
Edit existing images
python3 ${CLAUDE_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 ${CLAUDE_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 ${CLAUDE_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). Use ONLY when the user explicitly names OpenAI or GPT as the provider: "gpt image", "openai image", "generate image with openai", "用 openai 画图", "用 GPT 生成图片". For generic image requests without a provider, use nanobanana-skill instead. Do NOT use for diagrams (架构图/流程图) — draw those with Mermaid or code.'
4allowed-tools: Read, Write, Glob, Grep, Task, Bash(cat:*), Bash(ls:*), Bash(tree:*), Bash(python3:*)
5metadata:
6 source: https://skillmd.com/skills/feiskyer/gpt-image-skill
7---
8
9# GPT Image Skill
10
11Generate or edit images using OpenAI's GPT Image models through a bundled Python script.
12
13## Requirements
14
151. **OPENAI_API_KEY**: Must be configured in `~/.gpt-image.env` or `export OPENAI_API_KEY=<your-key>`
162. **OPENAI_API_BASE** (optional): Custom API base URL for compatible endpoints (e.g. Azure OpenAI, proxies). Set in `~/.gpt-image.env` or export it.
173. **Python3 with dependencies**: openai, Pillow. Install via `python3 -m pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt` if not installed yet.
184. **Executable**: `${CLAUDE_SKILL_DIR}/gpt_image.py`
19
20## Instructions
21
22### For image generation
23
241. Ask the user for:
25 - What they want to create (the prompt)
26 - Desired size (optional, defaults to 1024x1024)
27 - Output filename (optional, auto-generates UUID-based name if not specified)
28 - Model preference (optional, defaults to gpt-image-2)
29 - Quality (optional, defaults to auto)
30 - Number of images (optional, defaults to 1)
31
322. Run the script:
33
34 ```bash
35 python3 ${CLAUDE_SKILL_DIR}/gpt_image.py --prompt "description of image" --output "filename.png"
36 ```
37
383. Show the user the saved image path when complete.
39
40### For image editing
41
421. Ask the user for:
43 - Input image file(s) to edit (up to 3)
44 - What changes they want (the prompt)
45 - Output filename (optional)
46
472. Run with input images:
48
49 ```bash
50 python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit --prompt "editing instructions" --input image1.png image2.png --output "edited.png"
51 ```
52
53## Available Options
54
55### Models (--model)
56
57- `gpt-image-2` (default) — Latest model with strong instruction following, text rendering, and broad world knowledge
58- `gpt-image-1.5` — Mid-tier model
59- `gpt-image-1` — First-generation GPT image model
60- `gpt-image-1-mini` — Lightweight, faster generation
61
62### Sizes (--size)
63
64- `1024x1024` (default) — Square
65- `1024x1536` — Portrait (2:3)
66- `1536x1024` — Landscape (3:2)
67- `auto` — Let the model decide
68
69### Quality (--quality)
70
71- `auto` (default) — Model decides optimal quality
72- `high` — Higher detail, slower
73- `medium` — Balanced
74- `low` — Fastest
75
76### Output Format (--format)
77
78- `png` (default) — Lossless
79- `jpeg` — Smaller file size
80- `webp` — Modern format, good compression
81
82### Background (--background)
83
84- `auto` (default) — Model decides
85- `transparent` — Transparent background (png/webp only)
86- `opaque` — Solid background
87
88### Other Options
89
90- `--n <count>` — Number of images to generate (default: 1)
91- `--output <filename>` — Output filename (default: auto-generated)
92
93## Examples
94
95### Generate a simple image
96
97```bash
98python3 ${CLAUDE_SKILL_DIR}/gpt_image.py --prompt "A serene mountain landscape at sunset with a lake"
99```
100
101### Generate with specific size and output
102
103```bash
104python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
105 --prompt "Modern minimalist logo for a tech startup" \
106 --size 1024x1024 \
107 --quality high \
108 --output "logo.png"
109```
110
111### Generate landscape image
112
113```bash
114python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
115 --prompt "Futuristic cityscape with flying cars" \
116 --size 1536x1024 \
117 --output "cityscape.png"
118```
119
120### Generate with transparent background
121
122```bash
123python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
124 --prompt "A cute cartoon cat mascot" \
125 --background transparent \
126 --format png \
127 --output "mascot.png"
128```
129
130### Generate multiple images
131
132```bash
133python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
134 --prompt "Abstract art in the style of Kandinsky" \
135 --n 3 \
136 --output "art.png"
137```
138
139### Edit existing images
140
141```bash
142python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit \
143 --prompt "Add a rainbow in the sky" \
144 --input photo.png \
145 --output "photo-with-rainbow.png"
146```
147
148### Combine multiple reference images
149
150```bash
151python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit \
152 --prompt "Create a gift basket containing all items shown" \
153 --input item1.png item2.png item3.png \
154 --output "gift-basket.png"
155```
156
157### Use a different model
158
159```bash
160python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
161 --prompt "Detailed portrait of a cat in watercolor style" \
162 --model gpt-image-1 \
163 --output "cat-portrait.png"
164```
165
166## Error Handling
167
168If the script fails:
169
170- Check that `OPENAI_API_KEY` is exported
171- If using a custom endpoint, verify `OPENAI_API_BASE` is correct
172- Verify input image files exist and are readable (for editing)
173- Ensure the output directory is writable
174- Check that the model name is valid
175
176## Best Practices
177
1781. Be descriptive in prompts — include style, mood, colors, composition details
1792. For logos/icons, use square size (1024x1024) with transparent background
1803. For social media, use portrait (1024x1536) for stories or square for posts
1814. For wallpapers/headers, use landscape (1536x1024)
1825. Use `high` quality for final output, `auto` for quick iterations
1836. GPT Image models excel at text rendering — include text in prompts when needed
1847. For editing, provide clear instructions about what to change and what to keep