codex-image

codex-image 是做什么的？

通过用户的 ChatGPT 订阅，使用 GPT Image 生成和编辑图像。输出保存到 ./generated_images/ 目录（或 --out-dir / --out）。

如何运行

所有操作都通过一个脚本完成。请解析包含此 SKILL.md 的绝对目录（您的宿主环境会在技能加载时宣布该路径——下文将其写为 <skill-dir>），然后运行：

bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]

切勿直接调用裸的相对路径 scripts/generate.sh：您的工作目录是用户的项目，而不是技能的安装位置（不同代理的安装位置不同——~/.claude/skills/、~/.agents/skills/、~/.opencode/skills/、项目本地的 .claude/skills/ 等）。

脚本会为您检查以下要求：

• 在 PATH 上存在 python3 ≥ 3.10（否则需要 bash + 标准库 Python）。
• Pillow——仅用于 --format webp 和 --transparent-mode chroma。 默认不安装；如果运行需要，这些命令会快速失败并给出安装命令（python3 -m pip install 'Pillow>=10'）。普通的 --transparent 不需要它。请在使用这两个功能前先说明此前提。
• Codex CLI 已登录。如果未登录，脚本会退出并显示 Run: codex login——请将该信息转达给用户，而不要自行处理身份验证。

运行 bash "<skill-dir>/scripts/generate.sh" --help 可查看完整的标志列表；在自行构造标志前请查阅该帮助。如果宿主代理支持输入类型的斜杠命令，/codex-image "<prompt>" --flags 是对此脚本调用的面向用户的简写。

该脚本是机械性的——它不做任何语义路由。延续处理、批量决策和背景移除的调度是您的工作，需根据对话上下文决定。

GPT Image 2.5

OpenAI 提供了 gpt-image-2.5-sunburst（用于精确编辑）和 gpt-image-2.5-flare（用于更快的日常生成）。 要请求特定模型，请传递 --image-model <model-id>；省略该标志则保留 Codex Responses 的默认选择。 该标志在订阅传输模式下是实验性的：2026年9月8日的实况测试请求了每个变体，但两个响应都报告为 gpt-image-2-codex。 不要仅凭一次成功的请求就声称支持 2.5 升级。一个遗留的响应别名或 C2PA 版本 2.0 也不证明使用了更旧的权重：在 OpenAI 2.5 公告中发布的图像携带的就是该旧版本的来源证明。 当报告的模型不同或缺失时，脚本会发出警告；请在旁注文件中单独检查 image_model 和 requested_image_model。 --orchestrator 选择调用图像工具的主线模型，而不是 Sunburst 或 Flare。请省略它：脚本会使用账户列表中最新的 Sol 级模型（gpt-<version>-sol），这样退役的模型就不会破坏它。请求会发送到 Codex 自身配置指向 Codex 的任何位置：自定义的 model_provider（如代理）、openai_base_url 中继或 chatgpt.com。

请阅读 GPT Image 2.5 兼容性 以了解已验证的传输行为及官方来源。 公开 API 对模型选择、xhigh/max 和透明度的支持并不等同于 Codex Responses 上的相同行为。

延续处理

当请求修改紧接前一轮生成的图像时（“调暗一些”、“现在加一顶帽子”、“提高对比度”），请传递 --from-last——脚本会自动重用上一次生成（跟踪在 ~/.codex-image/last.json 中），这样您就不必从对话记录中找回路径。

对于编辑显式指定的文件或更早的生成结果，请传递 --input <path|url>（可重复使用；与 --from-last 组合最多 16 个引用；即技能引用上限）。

当请求是一个全新的主题时——即使用户说“现在做…”——也请不要传递任何引用，从头生成。如果您猜测错误且用户说“不，我是要一个新的”，请重新运行且不加引用。

用户仅用于提供风格、构图或氛围的图像是生成的参考，而不是编辑目标——请通过 --input 传递它们，但将提示描述为一个新图像（“以图像 2 的风格”）。当混合多个输入时，请在提示中按索引和角色标注每个输入（图像 1：编辑目标，图像 2：风格参考）。

生成后：先查看，再报告

在告诉用户完成之前，请查看保存的图像文件，并对照请求检查：主题、构图、任何逐字呈现的文字内容以及用户声明的每一个约束。如果有问题，通过一次有针对性的更改（使用 --from-last）进行迭代，并重申那些不能漂移的不变量。不要在一次重新运行中堆叠多个修正，也不要报告您尚未查看过的路径。

保存规范：输出默认存放在 ./generated_images/。如果图像最终将用于用户的项目，请将其复制或移动到实际位置（并更新所有引用它的代码）——不要将项目资产遗留在临时目录中。切勿覆盖用户未要求替换的已有资产；应改为写入带版本号的兄弟文件（如 hero-v2.png）。

透明图像

当用户需要透明背景时，请添加 --transparent。仅此而已——无需调度决策、无需 Pillow、也无需您来编排后处理步骤。

脚本直接要求模型输出 alpha 通道：它会发送 background: "auto" 并在提示末尾附加一句话，后端会返回 RGBA 格式。不要传递 --background transparent；该值会被此后端拒绝（docs/adr/0001-request-transparency-in-the-prompt.md 解释了原因，以及为什么看似正确的“修复”其实是错误的）。

如果您自己测试了后端并看到 "Transparent background is not supported for this model."，请不要得出结论认为透明度不可用。 该 400 错误是参数被拒绝，而非能力被拒绝。当在提示中要求时，模型会返回真正的 alpha 通道，这正是 --transparent 所做的。那些声称原生透明度需要 gpt-image-1.5 或 OPENAI_API_KEY 的建议是属于 0.2.0 版本之前的错误信息；如果您正在阅读这些建议，说明您安装的技能已过时。请检查此文件中的 metadata.version——它应为 0.2.0 或更高版本。

编写提示时需要注意两件事：

• 描述主体，而不是场景。 提示优于参数。“阳光工作室中木桌上的一个杯子”可能会渲染出整个工作室，而不是单独隔离出杯子。请明确指出主体及其材质；省略周围环境。
• 不要自行添加禁止项。 附加后缀特意不做任何禁止。如果用户要求投影，就让他们得到——它会以正确合成的方式渲染到 alpha 中。自行添加“无阴影，无背景”会覆盖用户的意图。

生成后，请查看文件并确认 alpha 通道确实存在。当结果没有 alpha 或完全不透明时，脚本会在 stderr 上发出警告；收到此警告后，应通过一次有针对性的更改重新生成，通常是移除场景性语言。

后备阶梯，仅当原生透明度效果不佳时使用（已在非透明主体上验证；头发、玻璃、烟雾和半透明材质未经测试）：

升级步骤	操作
重新提示	移除场景/背景语言，仅命名主体
提高质量	--quality medium 用于精细边缘和小文字
色度抠图	--transparent-mode chroma（需要 Pillow）——您控制关键板
Adobe MCP	--transparent-mode chroma --bg-tool=none，然后调用本会话中暴露的任何 Adobe 背景移除工具（查找名称包含 remove_background 的 MCP 工具）并用 alpha 结果覆盖文件。处理半透明材质的最佳选择

色度边缘修复：薄边缘 → --edge-contract 1；哑光主体上的锯齿边缘 → --edge-feather 0.25。更深入的失败模式：references/transparent-image-tips.md。

质量、成本与时间限制

• 默认质量为 --quality high；接受的值有 low、medium、high、xhigh、max 和 auto。草稿阶段建议从 low 开始。Codex Responses 可能会覆盖质量设置；请在声称某个级别已交付之前，检查旁注文件中的 resolved_quality 或 --verbose 输出。
• 生成过程会消耗用户 ChatGPT 套餐的限额。延迟因模型、提示、质量和服务负载而异。
• 在单个请求中生成了 3 张以上图像前，请先与用户确认。
• 切勿无限循环。“好多张” / “整套” → 选择一个合理的默认值（4 张）并提供继续的选项。
• 遇到 HTTP 429 错误时请立即停止，不要重试。

常见工作流程

# 单次生成
bash "<skill-dir>/scripts/generate.sh" "雨夜中的黄色出租车"

# 延续上一次生成
bash "<skill-dir>/scripts/generate.sh" "现在加入升腾的蒸汽" --from-last

# 编辑显式指定的参考图像
bash "<skill-dir>/scripts/generate.sh" "把它变成蓝色" --input ./mug.png

# 透明背景（来自模型的原生 alpha；不需要 Pillow）
bash "<skill-dir>/scripts/generate.sh" "一个咖啡杯" --transparent

# 透明背景，并包含用户要求的投影（会保留在 alpha 中）
bash "<skill-dir>/scripts/generate.sh" "一个带有柔和投影的咖啡杯" --transparent

# 色度抠图后备方案，当原生效果不佳时（需要 Pillow）
bash "<skill-dir>/scripts/generate.sh" "一个玻璃罐子" --transparent --transparent-mode chroma

# 不同的尺寸 / 格式 / 质量
bash "<skill-dir>/scripts/generate.sh" "英雄横幅" --size 2048x1152 --format webp --quality low

令牌编辑（安全）

切勿打印或记录用户的 access_token、id_token、refresh_token 或任何 Authorization: Bearer ... 标头。该技能的 Python 模块会自动进行编辑；您不得通过自行读取 ~/.codex/auth.json 或在错误消息中输出令牌来撤销此操作。

何时不调用

• 矢量图、SVG、ASCII 艺术或 LaTeX 图表 → 使用专用的矢量或图表工具。
• 用户明确要求使用不同的模型或产品（DALL-E、Stable Diffusion、Midjourney）→ 交由该工具处理。

对于生产级的 Logo/品牌工作，请调用——但要设定预期：生成探索性方案，并通过单次更改的 --from-last 迭代进行优化，而不是承诺一次生成就能完成最终资产（模板请参见 references/prompting-cookbook.md）。

参考文档

当您需要更深入的了解时，请阅读 <skill-dir>/references/ 中的文件：

• api-recipe.md —— 规范的请求体、标头、被拒绝的字段、透明度机制、SSE 解析
• prompting-cookbook.md —— 提示基础 + 用例模板（Logo、产品照片、UI 原型、信息图）
• transparent-image-tips.md —— 原生透明度的工作原理、遇到困难的情况以及色度抠图后备方案

仓库级上下文：CONTEXT.md（术语表——三种传输模式在其中定义）和 docs/adr/（为什么透明度是在提示中请求而非通过参数请求）。