gpt-image-2-skill

通过统一的 CLI 界面运行图像生成与编辑，无需理会不同提供商之间的差异。scripts/gpt_image_2_skill.cjs 中的 Node 封装程序会解析底层 Rust 二进制文件（环境变量覆盖 → 内置 Skill 二进制文件 → 已安装的二进制文件 → Tauri App 内置 CLI → 仓库 cargo run → 缓存的发行版 → 引导下载），并转发所有标志。在 glibc Linux 上，发行版引导会先尝试 GNU 归档，然后将静态 musl 归档用作沙箱回退方案。

何时使用此 Skill

• 生成或编辑图像，并获取 Agent 可解析的结构化结果。
• 在 OPENAI_API_KEY、OpenAI 兼容的 base URL 和 Codex auth.json 之间切换，无需更改命令格式。
• 遵循 $CODEX_HOME/gpt-image-2-skill/config.json 中的共享提供商配置，让 CLI、App 和 Skill 使用相同的默认提供商。
• 需要最终的透明 PNG 交付文件、蒙版、自定义尺寸（最大 4K）或原始请求正文。
• 希望在 stderr 上实时查看进度事件（重试、多部分准备、Codex SSE），同时在 stdout 上输出最终 JSON。

快速开始

始终传入 --json，确保结果为机器可读格式。需要查看进度时，添加 --json-events。

# 1. Confirm runtime + provider readiness
node scripts/gpt_image_2_skill.cjs --json config inspect
node scripts/gpt_image_2_skill.cjs --json doctor
node scripts/gpt_image_2_skill.cjs --json auth inspect

# 2. Generate a final transparent PNG deliverable
node scripts/gpt_image_2_skill.cjs --json --json-events \
  transparent generate --prompt "..." --out /tmp/asset.png \
  --size 2K --quality high

# 3. Generate a normal image (auto-selects provider; OpenAI first, then Codex)
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images generate --prompt "..." --out /tmp/out.png \
  --format png --size 2K

# 4. Edit a reference image (OpenAI multipart)
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images edit --prompt "..." --ref-image /tmp/in.png --out /tmp/out.png

# 5. Remove a controlled background from existing source images
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --input /tmp/source-green.png --out /tmp/asset.png \
  --method chroma --matte-color auto --strict

# 6. Verify the final file before delivery
node scripts/gpt_image_2_skill.cjs --json \
  transparent verify --input /tmp/asset.png --profile icon --strict

# 7. Raw request escape hatch
node scripts/gpt_image_2_skill.cjs --json \
  request create --request-operation generate \
  --body-file /tmp/body.json --out-image /tmp/out.png --expect-image

# 8. Self-test (calls doctor + auth inspect)
node scripts/selftest.cjs

使用 --provider openai、--provider codex 或 config inspect 中任意命名的提供商来指定提供商；保留默认的 --provider auto 时，会优先使用 default_provider。使用 --openai-api-base https://... 覆盖旧版 OpenAI base URL。

本地 Codex 生图（2026-09-09 更新）

以下 CLI 示例使用 Responses 路径。复现最新 Codex App 时，应区分宿主原生 image_gen.imagegen 的独立 Images 路径；见 references/codex-native-imagegen.md。原生工具成功不代表 CLI 已适配，服务端别名也不能证明实际权重版本。

用户指定 Codex 时，必须显式传入 --provider codex，避免共享配置将请求路由到 OpenAI 兼容服务。下面的命令从 Skill 目录执行，使用本地 Codex 登录，无需 OpenAI API key：

node scripts/gpt_image_2_skill.cjs --json --provider codex doctor
mkdir -p output
node scripts/gpt_image_2_skill.cjs --json --json-events --provider codex \
  images generate --model gpt-6-astra \
  --prompt "一只橙色纸雕小狐狸坐在蓝绿色月牙上，深蓝背景" \
  --out output/codex-fox.png --format png --size 1024x1024 \
  > output/result.json 2> output/events.jsonl

• 当前 CLI 的 Codex 默认值仍是 gpt-5.4；本地实测发现 ChatGPT 账户后端已拒绝该模型。示例显式使用本次验证的 gpt-6-astra，其他账户仍需核实可用模型。
• --model 是外层调用工具的模型，不能填写 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst。这两个是图像模型 ID。
• 普通命令未指定 tools[].model，由 Codex 服务端选择绘图模型。请读取 response.created 类型的 SSE 日志中的 data.response.tools[].model；不要将 CLI 摘要中的 delegated_image_model 当作实测结果，该字段在当前版本中仍硬编码为 gpt-image-2。
• 只有最终 JSON 的 ok: true、图片文件确实存在且经过视觉检查，才能报告生图成功。请求被接受或进入 generating 状态都不代表已完成。
• 出现 HTTP 400 模型不受支持错误时，应修正模型；不要改用其他提供商。遇到额度、权限或认证错误时，应报告原因，不要自动切换到付费 API。
• 对照测试发现：size 参数本身不能保证实际生效；将尺寸和比例写入提示词曾准确生成 1536×1024 图像，参数冲突时以提示词为准，但 4K 提示词仍未生成 4K 图像。不要根据请求值报告实际尺寸。
• 参数并非都无效：output_format 确实决定 PNG/JPEG；background=opaque 会覆盖透明提示词，生成带 RGB 棋盘格的假透明图像。透明候选应使用 auto，并检查真实 alpha；无法通过提示词保证 quality。
• 显式请求 2.5、服务端返回的模型以及透明背景限制，见 references/codex-local-verification.md。

Image 2.5 与运行时能力边界

OpenAI 官方已列出 gpt-image-2.5-flare 和 gpt-image-2.5-sunburst，可在 OpenAI Image API 中通过 --model 显式选择；这不代表 Codex 订阅后端已支持相同的模型选择。请保留用户指定的模型和共享配置。

2.5 的公共 API 支持 xhigh / max 质量和原生透明 PNG/WebP；当前 Rust CLI 和桌面生成界面已支持 low|medium|high|xhigh|max|auto。xhigh/max 仅适用于支持这些选项的 API 模型，不能保证 Codex 订阅后端也支持。Codex 的原始请求操作必须是 responses，不能使用 generate。

官方依据：Flare、Sunburst、图像生成指南。

防止静默降级与中文质量验收

• 用户要求使用 Image 2 或 2.5 时，不得为了透明效果、速度或重试失败而自行改用 1.5，也不得切换提供商来掩盖失败。
• 区分请求模型、服务端报告的模型和实际权重版本。Codex 只返回别名或未提供版本字段时，应将实际版本标记为 unknown；不能保证后端未回退，也不能仅凭中文表现或透明 alpha 推断版本。
• 复杂中文须核对原文：分别检查常规长句、金额、近形字、生僻字和标点。2026-09-09 新增的 4 张对照图中，两条路径均能生成清晰的常规中文和真实透明效果，但都未能正确保留“戊戌戍”等辨字内容及全部生僻字，因此不能宣称全文准确。
• 最新官方提示词指南已将 Image 2 透明列为 preview，2.5 两款均支持透明；“真透明意味着 1.5”已不是有效判据。公开 API 支持不代表 Codex 订阅路径使用相同参数时必然成功。
• 无法验证模型身份时，不要将质量测试包装成身份认证。此处是 Skill 执行要求，并非已实现的服务端版本锁定功能。

运行时新鲜度检查

使用新近记录的命令组之前，尤其是 transparent generate、transparent extract 或 transparent verify，请确认实际 CLI 运行时足够新。技能文件、Tauri App 包、npm 全局 CLI、通过 cargo 安装的 CLI 和包装器缓存可能各自出现版本偏差。

首先检查上游最新 CLI 版本：

npm view gpt-image-2-skill version

然后优先查找 Tauri App 内置的 CLI。将 App 包视为由用户管理的软件：如果它存在但版本低于上游版本，请先询问用户，再更新或替换该 App。

APP_CLI="/Applications/GPT Image 2.app/Contents/Resources/bin/gpt-image-2-skill"
[ -x "$APP_CLI" ] && "$APP_CLI" --version

如果不存在 App 包 CLI，请检查 shell CLI。如果找不到它，或其版本低于上游版本，请静默地用 npm 更新 CLI 依赖，然后确认当前 shell 解析到的是新二进制文件：

command -v gpt-image-2-skill || true
gpt-image-2-skill --version || true
npm install -g gpt-image-2-skill@latest
command -v gpt-image-2-skill
gpt-image-2-skill --version

更新后，运行技能包装器的冒烟测试：

node scripts/gpt_image_2_skill.cjs --json doctor
node scripts/selftest.cjs

如果文档中记录的子命令报错 unrecognized subcommand，请先排查运行时是否过旧，而不是修改提示词或提供方。为确保技能执行结果可复现，优先使用此技能目录中的包装器；但如果示例或用户命令直接调用 gpt-image-2-skill，也要确保裸 CLI 是最新版本。

共享配置

用户要求添加或固定提供方时，请使用 CLI 配置接口：

node scripts/gpt_image_2_skill.cjs --json config path
node scripts/gpt_image_2_skill.cjs --json config add-provider \
  --name my-image-api \
  --type openai-compatible \
  --api-base https://example.com/v1 \
  --api-key sk-... \
  --set-default
node scripts/gpt_image_2_skill.cjs --json config test-provider my-image-api

CLI、App 和 Skill 支持以下凭据来源：file、env 和 keychain。文件凭据存储在共享配置文件中；JSON 输出会对其进行脱敏。

标志与提示词——各自的控制内容

输出属性优先通过接口参数表达，但 Codex 后端可能会归一化或忽略参数。提示词可以表达期望，但最终必须读取实际返回值并检查图片；不要将任何单一参数或提示词视为执行保证。

属性	CLI 标志
输出背景（透明／不透明／自动）	--background auto|transparent|opaque
输出尺寸	--size 2K、--size 4K 或 --size WIDTHxHEIGHT
输出格式	--format png|jpeg|webp
压缩级别	--compression 0..100
渲染质量	--quality low|medium|high|auto
图片数量	--n <count>（仅限 OpenAI）
编辑蒙版区域	--mask <png>（仅限 OpenAI）

提示词用于描述内容与视觉意图；--background opaque 只表示不透明，不会指定白色。还需在提示词中明确要求白色背景。对于 Codex，透明提示词配合 background=auto 可能生成真正的 alpha 通道，而显式透明参数目前可能报错；请以实际测试和文件检查结果为准。

提供方差异：在 Codex 普通命令中，--n、--moderation、--mask 和 --input-fidelity 会返回 unsupported_option。--background 会写入 Codex 请求，但不能据此保证上游实际执行；本次原始透明背景请求被后端拒绝。公共 Image API 与 Codex 后端的能力必须分别验证。

透明 PNG 交付物

在本地对照测试中，Codex 显式设置 background=transparent 的请求被拒绝，但使用 background=auto 配合透明提示词曾成功生成真正的 RGBA 图片。可以将后者作为候选路径，但必须验证 alpha 通道和严格交付指标；本次样本因全透明区域残留 RGB 未通过严格验收。已符合要求的原生透明图片无需再次抠图。需要本地处理时，请使用以下流程；OpenAI 2.5 公共 API 的原生透明输出也必须经过同样的验收：

• transparent generate — 提示词生成最终 PNG。它会生成受控的哑光源图，在本地提取 alpha，验证结果，并且只有最终 PNG 通过透明度检查时才会成功。
• transparent extract — 从你自己生成的受控源图中本地移除背景。它不是适用于任意照片的通用背景移除工具。
• transparent verify — 交付前对任何 PNG 进行最终检查。文件必须通过验证或任务失败时，请使用 --strict 和正确的 --profile。

只有最终文件包含真正的 PNG alpha 通道并通过验证，透明交付物才有效。视觉上看似透明、白色背景或棋盘格图案都不够。

--strict 基于配置文件：

配置	用途	额外严格要求
generic	常见的 alpha／文件检查	不会对非常规素材过度检查
icon	干净的单主体图标和道具	要求主体核心干净且不透明、留有边距、杂散噪点少
product	产品／物体抠图	与 icon 类似，并检查残留和边缘
sticker	贴花、徽章、多细节道具	比 icon 更能容许有意保留的小组件
seal	带内部标记的印章、封印、徽标	允许环形加中心符号等分离组件
translucent	玻璃、液体、水晶	要求存在部分透明像素
glow	光带、火焰、烟雾、粒子	要求存在部分透明像素并留有透明边距
shadow	柔和阴影素材	要求存在部分透明像素并留有透明边距
effect	硬 alpha 粒子、爆发效果、UI 效果	要求留有透明边距，但不要求存在部分透明像素

该 CLI 有意不充当材质分类器。Agent 应根据素材选择生成提示词和抠图方法：

素材类型	生成指导	抠图指导
不透明物体、图标、贴纸、产品	生成单个孤立主体，留有清晰边距，并使用完全平坦的色度抠图底色。选择与物体颜色不同的底色。	transparent generate 或 transparent extract --method chroma --matte-color auto
细边缘、头发、毛皮、蕾丝、链条、网状物	使用高分辨率、强烈的主体／背景对比，不要有接触阴影，也不要包含与背景同色的细节。如果边缘受到污染，可尝试洋红／青色／绿色底色。	必要时使用带 --spill-suppression 的色度抠图，然后用 --expected-matte-color 验证；如果仍有残留，则更换底色后重试。
玻璃、水晶、液体、全息影像	要求在纯黑和纯白背景上分别生成居中的素材，并保持几何形状一致。尽可能使用参考／编辑流程来保持对齐。	transparent extract --method dual --dark-image black.png --light-image white.png
光效、火焰、烟雾、薄雾、魔法粒子	生成深色和浅色背景版本。避免使用有纹理的背景；除非边缘效果有意为之，否则应避免辉光延伸到图像边缘。	优先使用双图抠图；验证 partial_pixels 不为零。
阴影	确定阴影是否属于素材的一部分。如果不属于，明确禁止生成接触阴影。如果属于，则在平坦底色上生成，并留出足够边距。	不透明阴影轮廓使用色度抠图；柔和半透明阴影使用双图抠图。
未知或非常规材质	不要先对其分类。生成受控的源图变体，运行候选抠图方法，并保留通过验证且边缘最干净的版本。	迭代时使用 --report-dir／--keep-sources，最终只交付 PNG 文件。

进行色度抠图时，--matte-color auto 会从图像边缘采样源图中实际的纯色背景。如果源图由 AI 生成，优先使用此选项，因为“纯 #ff00ff”之类的提示词通常会生成接近底色但 RGB 值并不完全一致的颜色。仅当源图背景颜色完全确定时，才使用显式指定的 --matte-color <name|#rrggbb>。

调整抠图参数时，只将 --material 用作宽泛提示，而不要用作主体分类器：可选值为 standard、soft-3d、flat-icon、sticker 或 glow。手动设置的 --threshold、--softness 和 --spill-suppression 会覆盖所选预设。

对于需要锁定风格的透明素材，transparent generate 仅接受提示词。使用 images edit --ref-image 和纯色 RGB 参考图创建受控的底色源图，然后运行 transparent extract。除非有意让 alpha／合成边缘行为影响编辑，否则不要使用透明 PNG 作为参考图。 GPT Image 2 可以在位图中准确呈现 UI 文本、数字、分数、标签和 Logo 标记，前提是它们属于预期作品的一部分。请在提示词中写明准确的文字或编号，并目视检查输出。只有当文本必须保持可编辑、可本地化、可通过程序更改，或在多个生成变体间完全一致时，才在宿主应用或设计工具中单独渲染文本。

示例：

# Simple asset: final transparent PNG, sources hidden unless there is a failure
node scripts/gpt_image_2_skill.cjs --json --json-events \
  transparent generate \
  --prompt "a polished fantasy sword game asset, no text, no frame" \
  --out /tmp/sword.png --size 2K --quality high

# Agent-controlled chroma flow
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images generate \
  --prompt "a silver necklace, centered, on a perfectly flat pure magenta background, no shadow" \
  --out /tmp/necklace-magenta.png --format png --size 2K
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --method chroma \
  --input /tmp/necklace-magenta.png --matte-color auto \
  --out /tmp/necklace.png --material sticker --strict

# Semi-transparent material flow
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --method dual \
  --dark-image /tmp/glow-on-black.png \
  --light-image /tmp/glow-on-white.png \
  --out /tmp/glow.png --strict

交付前务必检查 JSON 验证字段：passed、alpha_min、alpha_max、transparent_ratio、partial_pixels 和 warnings。同时检查质量字段：checkerboard_detected、touches_edge、edge_margin_px、stray_pixel_count、largest_component_ratio、matte_residue_checked、matte_residue_score、halo_score、transparent_rgb_scrubbed、alpha_health_score、residue_score、quality_score 和 failure_reasons。如果 passed 为 false，请勿将该文件作为透明 PNG 交付。如果对于色度抠图生成的 PNG，matte_residue_checked 为 false，请使用源哑光色，通过 --expected-matte-color 再次运行 transparent verify。

注意事项

• 当前运行时默认值仍是 OpenAI gpt-image-2 / Codex gpt-5.4；Codex 使用上面的显式模型示例，不能依赖旧默认值。
• 共同接受的 CLI 参数：--size、--quality、--format、--compression；Codex 服务端可能会规范化这些参数，应核对返回值和实际文件。
• 仅限 OpenAI 的选项：--n、--moderation、--mask、--input-fidelity；Codex 后台行为需要单独验证。
• 重试：最多 3 次，采用指数退避（1s → 2s → 4s）。Codex 401 会触发一次令牌刷新和一次重试。
• 尺寸别名：2K → 2048x2048，4K → 3840x2160。自定义 WxH 要求两条边均为 16 的倍数，最长边最大为 3840，像素数最多为 8,294,400，宽高比最大为 3:1。

参考文件

需要深入了解时按需加载：

• references/codex-native-imagegen.md — App 原生工具、独立 Images 端点与旧 CLI 调用路径的区别。
• references/codex-local-verification.md — 本地 Codex 生图命令、实测结果与模型识别边界。
• references/providers.md — OpenAI / OpenAI-compatible / Codex 的选择、身份验证来源、运行时发现、更新策略和解析顺序。
• references/sizes-and-formats.md — 尺寸别名、自定义约束、格式/质量/压缩/背景，以及通用标志与仅限 OpenAI 的标志。
• references/transparent-png.md — Agent 操作手册，涵盖提示词设计、受控哑光、双背景提取、验证和重试循环。
• references/json-output.md — --json 标准输出架构、成功和错误封装、各命令的数据形状。
• references/json-events.md — --json-events JSONL 阶段（request_started、multipart_prepared、retry_scheduled）和 Codex SSE 透传。
• references/troubleshooting.md — runtime_unavailable、auth_missing、Codex 401 刷新、重试策略、尺寸拒绝、内容审核和超时。

Codex 兼容性

Codex Skill 运行时会读取伴随文件 agents/openai.yaml（Claude Code 会忽略它）。两种运行时执行上述命令时，都会将 cwd 设为技能目录，因此 scripts/gpt_image_2_skill.cjs 这类相对路径在两种运行环境中都能解析。