Open Interpreter（Codex）imagegen 技能回退 CLI 参考：scripts/image_gen.py 的 generate、edit 与 generate-batch 全解析

本文围绕 imagegen 技能的 CLI 参考文档 展开，系统讲解其回退 CLI 脚本 image_gen.py 的三个子命令（generate / edit / generate-batch）的用法、默认值、gpt-image-2 的严格尺寸约束、透明背景回退路径以及批量并发控制。读完后你可以脱离内置工具、直接用该 CLI 调用 GPT Image 系列模型完成生图、改图与 JSONL 批量出图，并理解每一条约束背后的源码校验逻辑。

1. 这个 CLI 在整个 imagegen 技能中的定位

SKILL.md 将图像生成技能定义为恰好两种顶层模式：

• 默认内置工具模式（首选）：内置 image_gen 工具，无需 OPENAI_API_KEY；
• 回退 CLI 模式：即本文主角 scripts/image_gen.py，仅在用户显式要求使用 CLI/API/模型控制，或显式确认要用 gpt-image-1.5 走"真透明"回退路径时才启用，且必须设置 OPENAI_API_KEY。

CLI 参考文档的开篇就明确了它的适用边界：

• 该文档只服务于回退 CLI 模式，当用户明确要求走 scripts/image_gen.py / CLI / API / 模型控制，或明确确认透明输出要走 gpt-image-1.5 回退路径时才应阅读；
• generate-batch 只是回退路径下的一个 CLI 子命令，不是技能本身的顶层模式；用户请求中仅仅出现"batch"一词，不构成进入 CLI 模式的依据。

此外文档给出了一条硬约束：不要静默地把 CLI 的 gpt-image-2 或内置 image_gen 降级到 CLI 的 gpt-image-1.5，除非用户已经明确要求 gpt-image-1.5、scripts/image_gen.py 或 CLI 回退。

2. 快速上手：从任意仓库环境定位脚本

技能在用户机器上安装到 $CODEX_HOME/skills/.system/imagegen/（默认 CODEX_HOME 为 ~/.codex）。文档建议先导出稳定路径：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

依赖安装：真实 API 调用需要 openai 包（本地缩图还需要 pillow）。在 uv 管理的环境中，文档推荐继续使用 uv pip install ...（见 SKILL.md 的 Dependencies 一节：uv pip install openai / uv pip install pillow）。

2.1 Dry-run：零依赖、零网络的预演

--dry-run 不需要 OPENAI_API_KEY、不需要网络、也不需要 openai 包——它只打印将要发送的 API payload 和计算出的输出路径。这一点可以从源码印证：_ensure_api_key() 在 dry-run 下只发警告而不是报错（image_gen.py#L69-L76）：

def _ensure_api_key(dry_run: bool) -> None:
    if os.getenv("OPENAI_API_KEY"):
        print("OPENAI_API_KEY is set.", file=sys.stderr)
        return
    if dry_run:
        _warn("OPENAI_API_KEY is not set; dry-run only.")
        return
    _die("OPENAI_API_KEY is not set. Export it before running.")

最简 dry-run 示例：

python "$IMAGE_GEN" generate \
  --prompt "Test" \
  --out output/imagegen/test.png \
  --dry-run

约定：一次性 dry-run 会输出 API payload 与计算出的输出路径；仓库内的最终产物应放在 output/imagegen/ 下。

2.2 真实生成（需要 OPENAI_API_KEY + 网络）

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --out output/imagegen/alpine-cabin.png

2.3 图像编辑

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --out output/imagegen/sunset-edit.png

从源码看，edit 子命令把 --image 定义为 action="append"（可重复传多次），文件通过 _check_image_paths() 做存在性与 50MB 上限检查（image_gen.py#L93-L102、image_gen.py#L960），最终调用的是 client.images.edit(...)（POST /v1/images/edits）；generate 则调用 client.images.generate(...)（POST /v1/images/generations）（image_gen.py#L752、image_gen.py#L831）。API 侧的完整参数速查在同目录的 image-api.md。

3. 默认值与参数校验

CLI 参考文档给出的默认值清单，与源码中的常量完全一致（image_gen.py#L25-L43）：

配置项	默认值	说明
模型 --model	gpt-image-2	仅支持 gpt-image-* 家族（_validate_model() 强制前缀校验）
尺寸 --size	auto	gpt-image-2 支持约束内的任意 WIDTHxHEIGHT；旧模型仅 4 种固定值
质量 --quality	medium	取值 low|medium|high|auto
输出格式 --output-format	png	可选 png、jpeg/jpg、webp
一次性输出路径 --out	output/imagegen/output.png	目标已存在时除非 --force 否则失败
背景 --background	未指定	可选 transparent、opaque、auto
批量并发 --concurrency	5	范围 1–25
批量重试 --max-attempts	3	范围 1–10
--n	1	单提示词多变体，范围 1–10

几个值得注意的源码级校验细节：

• 模型前缀校验：_validate_model() 要求模型名以 gpt-image- 开头，否则直接退出——"This CLI is intended for GPT Image models" 不是口号而是硬校验（image_gen.py#L172-L176）；
• 尺寸必须匹配模型：gpt-image-2 走约束校验，其他 GPT Image 模型走固定白名单 {"1024x1024", "1536x1024", "1024x1536", "auto"}（image_gen.py#L146-L154）；
• 透明背景必须搭配可透明格式：_validate_transparency() 规定 background=transparent 时 output_format 只能是 png 或 webp，否则报错（image_gen.py#L179-L181）。

4. gpt-image-2 的尺寸约束与选型指南

gpt-image-2 是新的 CLI 回退工作的默认模型，文档给出的选型建议：

• 快速草稿、缩略图、快速迭代用 --quality low；
• 最终资产、密集文字、图表、身份敏感编辑、高分辨率输出用 --quality medium / high / auto；
• 正方形图通常最快，快速方形草稿用 --size 1024x1024；
• 用户要 4K 风格输出时用 --size 3840x2160（横）或 --size 2160x3840（竖）；
• 不要给 gpt-image-2 传 --input-fidelity（该模型对图像输入恒为高保真）；
• 不要给 gpt-image-2 用 --background transparent（默认透明图工作流是内置 image_gen + 平色键背景 + 本地抠图；见第 6 节）。

常用尺寸一览：1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840、auto。

尺寸约束（四条必须全部满足）：

• 最长边 <= 3840px；
• 两条边都必须是 16px 的倍数；
• 长边与短边之比 <= 3:1；
• 总像素数在 655,360 与 8,294,400 之间；
• 超过 2560x1440 总像素数的输出属于实验性档位。

这些约束直接对应源码中的 _validate_gpt_image_2_size() 实现，常量 GPT_IMAGE_2_MIN_PIXELS = 655_360、GPT_IMAGE_2_MAX_PIXELS = 8_294_400、GPT_IMAGE_2_MAX_EDGE = 3840、GPT_IMAGE_2_MAX_RATIO = 3.0，任一不满足都会 _die() 并打印对应错误信息（image_gen.py#L40-L43、image_gen.py#L121-L143）。

典型三档示例：

# 快速草稿
python "$IMAGE_GEN" generate \
  --prompt "A product thumbnail of a matte ceramic mug on a stone surface" \
  --quality low \
  --size 1024x1024 \
  --out output/imagegen/mug-draft.png

# 最终 2K 横版
python "$IMAGE_GEN" generate \
  --prompt "A polished landing-page hero image of a matte ceramic mug on a stone surface" \
  --quality high \
  --size 2048x1152 \
  --out output/imagegen/mug-hero.png

# 4K 横版
python "$IMAGE_GEN" generate \
  --prompt "A detailed architectural visualization at golden hour" \
  --size 3840x2160 \
  --quality high \
  --out output/imagegen/architecture-4k.png

5. quality、input fidelity 与 mask（仅限 CLI 回退）

文档特别强调：--quality、--input-fidelity、--mask 是显式的 CLI 控制项，不是内置 image_gen 工具的参数：

• --quality 对 generate、edit、generate-batch 均有效，取值 low|medium|high|auto；
• --input-fidelity 仅 edit 子命令可用，校验取值 low|high，且 gpt-image-2 不支持（传了会在 main() 的预校验阶段直接失败，报错信息见 image_gen.py#L197-L200）；
• --mask 仅 edit 子命令可用，只接受单个 mask。

示例：

python "$IMAGE_GEN" edit \
  --model gpt-image-1.5 \
  --image input.png \
  --prompt "Change only the background" \
  --quality high \
  --input-fidelity high \
  --out output/imagegen/background-edit.png

Mask 使用要点（文档原文全部继承）：

• 多图编辑时通过重复 --image 传入，顺序有意义，应在提示词中用索引+角色描述每张图；
• 图像与 mask 必须同尺寸、同格式，且各自小于 50MB（源码中的 MAX_IMAGE_BYTES = 50 * 1024 * 1024，image_gen.py#L45）；
• Mask 必须带 alpha 通道；
• 多输入图时 mask 作用于第一张图；
• 抠图是提示词引导的，不要承诺像素级精确的 mask 边界；
• 尽量使用 PNG mask；脚本对 mask 只做文件级检查/警告，不做完整预检（源码印证：_edit() 中 mask 非 PNG 只 _warn，超 50MB 也只 _warn，image_gen.py#L772-L779）；
• 编辑提示词中要重复不变量（如 "change only the background; keep the subject unchanged"）以减少漂移。

6. 真透明回退：gpt-image-1.5 是唯一支持 background=transparent 的路径

文档对透明输出的规则非常明确：gpt-image-2 不支持 background=transparent，因此"真·模型原生透明"只能走 gpt-image-1.5。默认透明图路径仍然是：内置 image_gen 生成平色键（chroma-key）背景图 + 本地运行 remove_chroma_key.py 抠出 alpha。

只有在用户显式确认（或事先已点名 gpt-image-1.5 / scripts/image_gen.py / CLI 回退）之后，才执行：

python "$IMAGE_GEN" generate \
  --model gpt-image-1.5 \
  --prompt "A clean product cutout on a transparent background" \
  --background transparent \
  --output-format png \
  --out output/imagegen/product-cutout.png

走这条路径时应向用户简要说明：内置 image_gen + 色键抠图才是默认透明路径，本次需要的是模型原生透明，而 gpt-image-2 不支持 background=transparent，所以必须用 gpt-image-1.5。这一点在 image-api.md 的模型对照表中也有同口径的描述。

7. 输出处理约定

• 临时 JSONL 输入与草稿文件放 tmp/imagegen/，用完删除；最终产物放 output/imagegen/；
• 目标文件已存在时重跑会失败，除非传 --force（源码中 _decode_write_and_downscale() 写入前检查 out_path.exists() and not force，image_gen.py#L377-L378）；
• --out-dir 会把一次性输出改为 image_1.<ext>、image_2.<ext> 的序号命名（_build_output_paths()，image_gen.py#L221-L232）；
• --n 大于 1 时文件名追加 -1、-2 后缀；
• 缩小副本默认使用 -web 后缀（--downscale-suffix 可覆盖；缩放用 Pillow LANCZOS，jpeg 输出会把透明通道合成白底，image_gen.py#L330-L361）。

8. 常用配方

8.1 带增广字段的生成

CLI 支持把结构化提示词字段拼进 prompt（--no-augment 可关闭，默认开启）：

python "$IMAGE_GEN" generate \
  --prompt "A minimal hero image of a ceramic coffee mug" \
  --use-case "product-mockup" \
  --style "clean product photography" \
  --composition "wide product shot with usable negative space for page copy" \
  --constraints "no logos, no text" \
  --out output/imagegen/mug-hero.png

从源码看，_augment_prompt_fields() 会把 use_case、scene、subject、style、composition、lighting、palette、materials、text、constraints、negative 这些字段渲染成 "Label: value" 的多行规格文本，夹着原始 --prompt 作为 Primary request 一起发送（image_gen.py#L260-L289），与 SKILL.md 中"共享 prompt schema"的标签保持一致。

8.2 生成 + 自动产出网页缩小副本

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --downscale-max-dim 1024 \
  --out output/imagegen/alpine-cabin.png

执行后除 alpine-cabin.png 外还会写出 alpine-cabin-web.png。

8.3 generate-batch：JSONL 并发批量出图

mkdir -p tmp/imagegen output/imagegen/batch
cat > tmp/imagegen/prompts.jsonl << 'EOF'
{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","composition":"wide-angle, low-angle","lighting":"volumetric light rays through drifting fog","constraints":"no logos or trademarks; no watermark","size":"1536x1024"}
{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","composition":"eye-level","constraints":"no logos or trademarks; no watermark","size":"1024x1024"}
EOF

python "$IMAGE_GEN" generate-batch \
  --input tmp/imagegen/prompts.jsonl \
  --out-dir output/imagegen/batch \
  --concurrency 5

rm -f tmp/imagegen/prompts.jsonl

批量模式的关键规则与实现细节：

• generate-batch 强制要求 --out-dir（image_gen.py#L974-L975）；
• --concurrency 控制并行度（默认 5，范围 1–25，image_gen.py#L968-L969），实现上用 asyncio.Semaphore 限流（image_gen.py#L631）；
• JSONL 中每行可以是纯字符串 prompt，或对象；空行和 # 开头行会被跳过（_read_jobs_jsonl()，image_gen.py#L443-L465）。单文件任务数上限 500（MAX_BATCH_JOBS，image_gen.py#L46）；
• 逐任务覆盖字段支持 size、quality、background、output_format、output_compression、moderation、n、model、out 及提示词增广字段（_merge_non_null() 实现"非 null 才覆盖"的合并语义，image_gen.py#L468-L473）；
• 批量模式下任务的 out 字段被当作 --out-dir 下的文件名处理；未指定时自动生成为 001-<prompt-slug>.<ext> 形式的序号命名（_job_output_paths()，image_gen.py#L476-L506）；
• --n 用于同一提示词的多个变体；generate-batch 用于多个不同提示词——多个不同资产应当每个资产一个 prompt/任务，并尽量用语义化文件名；
• 瞬时错误（429 限流、超时、连接重置）自动重试，退避为 min(60, 2^attempt) 秒或从异常中解析出的 retry-after（_generate_one_with_retries()，image_gen.py#L543-L568）；
• 默认失败不中断整批（单任务失败仅记录），传 --fail-fast 才会立即中止并取消其余任务（image_gen.py#L684-L699）；
• 批量执行结束码：全部成功为 0，任一任务失败为 1。

9. 其余可用参数速览

CLI 参考文档还确认了以下参数受支持：--prompt-file（与 --prompt 二选一）、--output-compression（0–100）、--moderation（auto 默认 / low）、--max-attempts、--fail-fast、--force、--no-augment。模型与尺寸相关的通用注意事项：

• 支持的尺寸取决于模型：gpt-image-2 支持上文约束内的弹性尺寸；旧版 GPT Image 模型只支持 1024x1024、1536x1024、1024x1536 或 auto；
• 真透明 CLI 输出要求 output_format 为 png 或 webp，且 gpt-image-2 不支持；
• 该 CLI 面向 GPT Image 模型，不要假设旧版非 GPT 图像模型的行为在此适用。

10. 网络与沙箱注意事项

真实 API 调用需要出站网络，而很多 Codex 环境默认禁用网络或要求命令级审批。同目录的 codex-network.md 澄清了一个常见误区：--ask-for-approval never 只是抑制审批提示，并不会开启网络；在 workspace-write 沙箱下还需显式配置。该文档给出的 ~/.codex/config.toml 示例模式：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

并提醒：开启网络并降低审批门槛会提高摩擦效率，但在运行不受信代码或处于不受信仓库时风险也更高。

11. 使用守则（Guardrails）

CLI 参考文档的守则章节值得整体保留：

• 激活正确环境后直接使用捆绑 CLI（python "$IMAGE_GEN" ...）；
• 不要自造一次性 runner（如 gen_images.py），除非用户明确要求自定义包装；
• 永不修改 scripts/image_gen.py 本身；缺什么能力就先问用户；
• 不要静默从 CLI gpt-image-2 或内置 image_gen 降级到 CLI gpt-image-1.5，除非用户已显式点名回退。

12. 相关文件索引

• 回退 CLI 文档：references/cli.md
• API 参数速查：references/image-api.md
• 共享提示词示例：references/sample-prompts.md、references/prompting.md
• 网络/沙箱说明：references/codex-network.md
• CLI 实现：scripts/image_gen.py
• 色键抠图后处理脚本（内置透明图路径使用）：scripts/remove_chroma_key.py
• 技能总纲：SKILL.md