gpt-image

gpt-image

用于 GPT Image 2 / 2.5 生成与编辑的 Agent 操作手册。使用提示词库和打包的 CLI。不要重新实现图像 API 代码。

操作流程

1. 分类请求并确定模型：generate、edit、inpaint 或 multi-reference；识别素材类型、精确文本、宽高比、参考图、安全限制以及预算/质量。在调用任何 API 前，应用以下模型选择规则。
2. 选择参考图路径：Image 2 沿用下方的图库优先工作流程。对于 2.5，精确的需求说明无需加载参考图；否则选择一个简短的任务切片。
3. 按需完善：保留需求说明。只有在填补具体缺口时，才添加特定图库案例、制作章节或模板；对于 2.5，不要将它们打包加载。
4. 酌情沟通：对于成本高昂、有歧义或需要高质量润色的调用，先展示 1–3 个匹配的方向及计划使用的尺寸/质量；每次最多询问一个简短问题。对于模型已确定且明确要求“立即生成”的请求，不要进行冗长讨论。
5. 预检，不产生副作用：如果已有 CLI/技能，则使用它。检查命令是否可用（command -v gpt-image）、工具管理器是否存在及其已安装工具列表，或运行时自身的技能注册表（如果可用）。在云端/托管运行时中，不要假定存在本地 home 路径。
6. 不要盲目设置：除非用户明确要求设置，否则不要重新安装、覆盖技能文件夹、创建/修改 .env 或写入 API 密钥。全局/共享安装仅在选择加入时进行。
7. 仅通过 CLI 执行：使用带有显式 --model 的 gpt-image 或 scripts/generate.py。对于常规图像请求，不要创建新的 generate.py、SDK 封装或临时脚本。
8. 报告结果：提供输出文件路径、关键标志；如有帮助，再给出一条简短的改进建议。

快速路径：已确认使用 2.5 模型 + 精确提示词 + “立即生成” → 预检并调用 CLI，无需强制进行参考图/制作环节。不要再次确认已明确且有效的模型。

模型选择与提示词调整

选项	API 模型 ID	建议用途
Flare	gpt-image-2.5-flare	快速通用生成和草稿
Sunburst	gpt-image-2.5-sunburst	精确参考图编辑和细节控制
Image 2	gpt-image-2	现有 Image 2 工作流程和兼容性

• 如果模型缺失、有歧义（例如“GPT 2.5”）或拼写错误，提出一个清晰的问题，列出 Flare、Sunburst 和 Image 2 及其权衡，然后等待回复。对于拼写错误，指出可能的预期选项，但不要悄悄纠正。不要将 gpt-image-2.5 视为 API 模型 ID。
• 对于当前任务，如果用户提供了准确的受支持模型 ID、从此菜单中明确选择了选项，或已确认过选择，则直接使用，无需再次询问。如果用户明确表示“由你选择”，简要说明选择理由并继续；根据任务和预算做决定，不要总是选择最昂贵的设置。
• 始终通过 --model 传入选定的 ID。CLI 为向后兼容保留了 gpt-image-2 作为默认值，但该默认值不能替代 Agent 对用户选择的确认。
• 将模型确认、费用讨论和 API 标志与最终图像提示词分开。仅在有助于完成任务时，使用下方针对特定模型的参考图路径。保留用户提供的精确文本、预期内容、参考图身份及编辑不变量；对提示词的重大修改须先获得确认。
• 除非用户要求生成更多，否则只生成一张图。不要擅自切换模型、改变提示词的实质内容，或运行多个模型/提示词变体或进行比较。生成额外的付费变体前，先询问。对于获准进行的相同提示词比较，除非用户要求变化，否则保持提示词、尺寸和质量一致。
• 当需要检查参数支持情况或验证状态时，查阅 references/models.md。如果出现模型无效、访问/403、配额或策略错误，报告错误并停止；不要自动切换模型或重写提示词后重试。

CLI 解析

优先调用顺序：

# Existing CLI on PATH
gpt-image --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Installed skill folder; use runtime-provided skill path when available
uv run "$SKILL_DIR/scripts/generate.py" --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Direct transient CLI when the user requested setup/one-off CLI execution
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image --model MODEL_ID -p "PROMPT" [options]

scripts/generate.py 是一个启动器：仓库本地的 src/gpt_image_cli → 已安装的 gpt-image → PATH 中的 gpt-image → 临时回退到 uvx/uv。

密钥和费用规则

• CLI 从进程环境变量中读取 OPENAI_API_KEY，然后读取 .env，最后读取 ~/.env，且不会覆盖现有环境变量；成功的 API 调用可能会计入用户的 OpenAI 账户。
• 如果主机/运行时支持平台原生管理的图像生成，且用户希望使用该方式，请使用主机工具，而非此 CLI。
• 如果未设置 OPENAI_API_KEY，请说明缺少密钥；如果用户有此要求，则使用主机原生图像生成功能；不要写入密钥。
• 如果用户希望避免使用本地密钥，请遵循 unset OPENAI_API_KEY；如果 .env/~/.env 中存在密钥，请告知用户在本次会话中将其移除或重命名，而不是设法绕过。
• 切勿打印密钥值。

标志

标志	值	用途
-p, --prompt	string	必需的提示词/编辑指令
-f, --file	path	输出路径；省略时自动命名
-i, --image	repeatable path	使用编辑端点；支持多个参考图
-m, --mask	PNG path	使用 alpha 蒙版进行修补；需要 -i
--model	gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst	Agent 必须明确传入已解析的选项
--size	1k、2k、4k、portrait、landscape、square、wide、tall 或字面值	画布尺寸
--quality	low、medium、high、auto；2.5 还支持 xhigh、max	费用/质量调节；请检查特定模型的限制
-n, --n	integer	图像数量
--background	auto、opaque；2.5 还支持 transparent	透明背景需要 PNG 或 WebP，不能使用 JPEG
--input-fidelity	low、high；默认省略	仅用于编辑；明确指定的 2.5 值会转发给 API，不代表其受支持
--moderation	auto、low	生成内容审核设置
--format	png、jpeg、webp	输出编码格式
--compression	0-100	JPEG/WebP 压缩率
--user	string	可选的最终用户标识符

质量起始建议（不作保证；保持用户已同意的设置）。对于 2.5，这些建议优先于较早的创作参考中固定的质量建议：

• low：低成本草稿和广泛探索；多个变体需要用户授权。
• medium：常规探索、风格探查，以及平衡成本。
• high：CLI 默认值，也是最终素材、密集文本、图表和 UI 的备选项。对于 2.5，请根据任务要求进行评估；不要假设 medium 不合格，也不要认为更高设置总是更好。
• xhigh / max：2.5 专属的高质量选项；提高已商定的质量设置前，请先讨论成本权衡。对预算敏感的请求不要自动使用这些选项。

尺寸策略：

• 默认/社交媒体方形：1k / 1024x1024
• 海报/手机/美妆：portrait
• 风景/游戏画面/照片：landscape
• 印刷/纸质图表：2k
• 宽屏主视觉：4k
• 竖版故事/横幅：tall

端点路由

模式	触发条件	端点
文生图	不带 -i	/v1/images/generations
参考图编辑	带一个或多个 -i	/v1/images/edits
图像修补	-i + -m	/v1/images/edits，并使用蒙版

错误信息应原样呈现到足以用于调试；退出代码：0 成功，1 API 错误/拒绝，2 参数错误/缺少密钥。

参考资料加载

• Image 2：打开 references/gallery.md，再打开一个匹配的 references/gallery-*.md 分类文件及其中实际使用的提示词。仅在需要时阅读 references/craft.md 或历史文件 references/openai-cookbook.md 的相关章节。
• Image 2.5：精准需求无需强制参考资料。如需指导，直接选择一个文件：references/openai-image-2.5-generation.md（照片／产品／插画）、references/openai-image-2.5-layout-and-text.md（文本／UI／图表／面板），或 references/openai-image-2.5-editing.md（参考图／蒙版／翻译）。
• 其他问题：references/openai-image-2.5.md 是可选索引；references/openai-image-2.5-migration.md 介绍迁移／比较；references/models.md 记录当前 API 参数和验证状态。
• 仅供额外参考：图库案例、针对性的 craft 章节，或 references/templates-gpt-image-2.5.md（社区改编内容，未经输出验证）。不要预先加载这些文件，也不要为 2.5 加载旧版 Cookbook。

只加载最小且有用的部分，不要同时加载两种模型路线。只有确实涉及混合任务时，才额外加载第二个任务部分。历史示例不能覆盖当前 API 说明或用户指定的模型／设置。

验证

• API 调用前：检查解析后的模型和显式指定的 --model、端点模式、尺寸、质量、输出路径，以及所需的参考图／蒙版文件。除非有明确需要，否则省略 --input-fidelity；不要假设 2.5 始终使用或接受 high。
• CLI 调用后：报告 CLI 打印的路径；若失败，显示 stderr。
• 编辑／局部重绘：确认 -i 路径存在；使用 -m 时确认该文件存在。

改编示例时，保留 Curated 与 Author + Source 元数据。将新收集的提示词添加到 Reference Gallery 后，再纳入 README。