| name | openai-image |
| license | MIT |
| description | 图像生成 / 改图 / 合成 skill,基于 OpenAI gpt-image-2,任意 OpenAI
兼容代理。当用户想"gpt生图、AI 出图、改背景、换风格、融合几张图、
做产品图/海报/UI mockup/角色立绘"或提到 gpt-image-2 时使用。
同样适用英文 generate / restyle。
|
openai-image
通过 Bash 调 scripts/generate.py 出图、scripts/edit.py 改图。
走 OpenAI Images API(POST /v1/images/generations + /v1/images/edits),
代理域名带 "claude" 仍可能是 OpenAI 兼容端点(与 Anthropic 无关)。
4 个工作流
python3 scripts/generate.py -p "A photorealistic cafe at golden hour" -f gpt_image_out/cafe.png
python3 scripts/edit.py -p "Change only the background to snow. Keep the subject, camera angle, lighting exactly the same." -i in.png -f gpt_image_out/winter.png
python3 scripts/edit.py -p "Place the dog from image 2 next to the woman in image 1." -i woman.png -i dog.png -f gpt_image_out/combined.png
python3 scripts/generate.py -p "..." -f gpt_image_out/x.png --json
python3 scripts/generate.py -p "..." --dry-run --json
--dry-run 不调 API,会校验输入文件存在 + 扩展名合法。
输出路径
-f <path> 显式指定输出(可以是文件或目录);不传 -f 时,产物落到 <cwd>/gpt_image_out/(cwd = OpenCode session 当前工作目录;DEFAULT_OUT_DIRNAME 见 scripts/lib/image_io.py)。目录不存在自动 mkdir。
-f gpt_image_out/cafe.png
-f gpt_image_out/
--out-dir /path/to/my/output
文件命名:YYYY-MM-DD-HH-MM-SS-<slug>.<ext>,--format jpeg|webp --compression N 时 Pillow 重编码。
关键约束
| 项 | 约束 |
|---|
| model | gpt-image-2(OpenAI 官方 2026-04-21 发布,见 https://platform.openai.com/docs/models/gpt-image-2) |
| size | 两边 16 倍数,长边 ≤ 3840,长宽比 1:33:1,总像素 65.5 万829 万;>2560 实验性。注意:OpenAI API 不严格校验 16 倍数——传非 16 倍数(如 1080x1920)API 接受但静默降级到最近的合规尺寸(如 1024x1536),用户拿到的不是请求的尺寸。skill 客户端 params.py:resolve_size 主动拦截,exit 2,早 fail-fast |
| quality | low / medium / high / auto |
| format | png(默认)/ jpeg / webp |
| reference | 1~16 张 png/jpg/webp,单张 ≤ 50MB |
| mask | 必须 .png,alpha: 不透明=保留,透明=重画 |
| prompt | 最长 32 000 字符 |
| retry | 408/409/429/5xx 退避 3 次(--retries 可调) |
| 字段降级 | 代理拒 background / moderation / output_compression / output_format 时自动去掉重试 |
| n | 强制 1(业务决策:省钱 + UI 单张够用) |
--background(transparent/opaque/auto)和 --moderation(low/auto)
是 OpenAI Images API 标准参数;--background 仅 generate.py 支持,
edit.py 不接(Images Edits API 本身不支持)。
UI 出图尺寸速查
以下尺寸都满足关键约束的 16 倍数规则。来源:https://platform.openai.com/docs/guides/image-generation。
PC 桌面软件
| 场景 | --size |
|---|
| 应用图标 | 1024x1024 (square) |
| 窗口截图(16:10) | 1536x1024 (landscape) |
| 全屏截图(16:9) | 2048x1152 (2k-wide) |
| 4K Hero | 3072x1728 |
移动 App
| 场景 | --size |
|---|
| iPhone 启动屏(15 Pro) | 1152x2560 |
| iPhone SE | 768x1280 |
| Android 启动屏 | 1088x1920 |
| iPad Pro 11 | 1664x2384 |
| App Store 截图 | 1280x2560 |
Web
| 场景 | --size |
|---|
| Hero 全宽(2:1) | 2048x1024 |
| 博客封面(3:2) | 1536x1024 (landscape) |
| OG Image(社交分享,~2:1) | 1216x640 |
| 长截图整页(1:3 临界) | 1024x3072 |
微信小程序
| 场景 | --size |
|---|
| 启动屏(9:16) | 1088x1920 |
| 分享卡片(4:3) | 512x384 |
| 商城 banner(5:2) | 800x320 |
| 商品主图(1:1) | 1024x1024 (square) |
环境配置
pip install 'openai>=1.68' 'Pillow>=10'
两个 env 必须都设(API key + Base URL):
| 用途 | env 变量 |
|---|
| API key | GPT_AGENT_KEY |
| Base URL | GPT_AGENT_URL |
Base URL 末尾 /v1 会自动补齐。实际访问的 endpoint:
generate.py → {BASE_URL}/images/generationsedit.py → {BASE_URL}/images/edits
OPENAI_API_KEY / OPENAI_BASE_URL 不读取——本 skill 只用 GPT_AGENT_*。
引用(按需加载)
| 场景 | 加载 |
|---|
| 完整 CLI 参数 / 退出码 / JSON schema / 测试 | references/cli-reference.md |
| 故障排查 | references/troubleshooting.md |
