imagegen Skill 的 CLI 回退模式完全指南scripts/image_gen.py 的生成、编辑与批量工作流【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文是 Codex skills 仓库中 imagegen 技能skills/.system/imagegen的CLI 回退模式技术参考讲解其核心脚本 scripts/image_gen.py 的三种子命令generate、edit、generate-batch的完整用法、全部参数、默认值、校验规则与实战配方。读完本文你将掌握如何在显式选择 CLI 路径后用一条条可复制的命令完成单张生成、图片编辑含掩码与输入保真度、以及基于 JSONL 文件的并发批量出图并理解脚本内部的参数校验、提示词增强、输出路径与重试机制等底层实现。使用前提CLI 回退模式仅在用户显式要求使用scripts/image_gen.py替代内置image_gen工具时才启用。内置image_gen工具是默认路径且不需要OPENAI_API_KEYCLI 回退模式的真实 API 调用则必须拥有网络访问能力与OPENAI_API_KEY只有--dry-run不需要。CLI 是什么三种子命令与定位根据 cli.md 的说明scripts/image_gen.py是fallback CLI 模式回退命令行模式的专用脚本提供三个子命令generate根据提示词生成一张新图片edit编辑一张或多张已有图片generate-batch从一个 JSONL 文件读取多个生成任务并批量执行从源码看脚本入口在 image_gen.py 的main()使用argparse的subparsers注册三个子命令且command参数为必选。默认模型为gpt-image-1.5源码常量DEFAULT_MODEL见 image_gen.py并只接受gpt-image-*前缀的模型GPT_IMAGE_MODEL_PREFIX校验逻辑见 _validate_model。脚本顶部的模块文档字符串也明确它默认采用结构化提示词增强工作流专用于 GPT Image 模型。快速开始环境变量与依赖安装设置稳定的 CLI 路径CLI 脚本位于$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py默认CODEX_HOME为~/.codex。在任意仓库中都建议先固化路径变量export CODEX_HOME${CODEX_HOME:-$HOME/.codex} export IMAGE_GEN$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py安装依赖按 SKILL.md 的依赖说明本仓库优先使用uv管理依赖# 必需OpenAI Python SDK真实 API 调用 uv pip install openai # 可选仅当需要降采样downscale时才需要 uv pip install pillow在 uv 托管环境中uv pip install ...是首选方式若在仓库外使用已安装的技能则用该环境的包管理器安装依赖。源码_dependency_hint()image_gen.py会在缺少包时给出同样的安装提示先激活仓库所选环境本地虚拟环境用source .venv/bin/activate若项目声明了依赖则优先走项目的uv sync流程。密钥与网络要求_ensure_api_key()image_gen.py逻辑真实调用前必须设置OPENAI_API_KEY环境变量否则直接报错退出dry-run 模式则仅给出警告继续执行。网络/沙箱相关注意事项见 codex-network.mdCodex 许多配置下默认禁止出网并要求审批需要网络访问与审批策略同时配合例如~/.codex/config.toml中设置approval_policy on-request、sandbox_mode workspace-write且[sandbox_workspace_write] network_access true。注意--ask-for-approval never只能抑制审批弹窗并不能自行开启网络。单张生成从 Dry-run 到真实调用Dry-run无网络、无 API 密钥--dry-run不发起真实 API 调用不要求openai包也不要求网络python $IMAGE_GEN generate \ --prompt Test \ --out output/imagegen/test.png \ --dry-rundry-run 会打印将要发送的 API 载荷JSON以及计算好的输出路径。源码中该逻辑位于 _print_request 与 _generate端点标记为/v1/images/generations同时会展示outputs与若指定降采样outputs_downscaled路径列表。仓库内的最终产物应放在output/imagegen/下。真实生成python $IMAGE_GEN generate \ --prompt A cozy alpine cabin at dawn \ --size 1024x1024 \ --out output/imagegen/alpine-cabin.png源码中真实路径走client.images.generate(**payload)image_gen.py并在写入前先输出提示“Calling Image API (generation). This can take up to a couple of minutes.”生成可能耗时数分钟。返回结果从result.data[].b64_json解码为字节后写盘见 _decode_write_and_downscale。编辑已有图片edit 子命令python $IMAGE_GEN edit \ --image input.png \ --prompt Replace only the background with a warm sunset \ --out output/imagegen/sunset-edit.pngedit调用 OpenAI 编辑端点/v1/images/edits即client.images.edit(...)见 image-api.md。源码 _edit 中有几个关键实现细节--image为actionappend参数可重复传入多个图片顺序有意义多图编辑时需在提示词中按索引与角色描述每张图。文件校验_check_image_pathsimage_gen.py会检查文件存在性并警告超过 50MB 的输入图。若传--mask脚本会检查掩码文件存在性并提示“Mask should be a PNG with an alpha channel”PNG 掩码为最佳实践掩码同样受 50MB 上限约束。编辑提示词中应重复不变式如change only the background; keep the subject unchanged以降低模型漂移drift。质量、输入保真度与掩码CLI 专属参数以下参数是显式 CLI 控制项并非内置image_gen工具的参数参数适用子命令取值范围说明--qualitygenerate / edit / generate-batchlow|medium|high|auto输出质量默认auto--input-fidelity仅 editlow|high输入图像保真度默认low--mask仅 edit图片路径可选的掩码图单个python $IMAGE_GEN edit \ --image input.png \ --prompt Change only the background \ --quality high \ --input-fidelity high \ --out output/imagegen/background-edit.png源码对应的白名单常量image_gen.py为ALLOWED_QUALITIES {low,medium,high,auto}与ALLOWED_INPUT_FIDELITIES {low,high,None}非法值会经_validate_quality/_validate_input_fidelity直接报错。注意 image-api.md 的模型差异说明gpt-image-1与gpt-image-1-mini会保留全部输入图但第一张图的纹理与细节最丰富gpt-image-1.5以更高保真度保留前 5 张输入图。此外掩码由提示词引导精确形状不保证高input_fidelity会显著增加输入 token 用量。输出处理路径、覆盖与降采样临时 JSONL 输入与草稿文件放在tmp/imagegen/最终产物放在output/imagegen/。重跑会因目标文件已存在而失败除非传入--force。源码在_decode_write_and_downscale中执行out_path.exists() and not force检查命中即报 “Output already exists ... (use --force to overwrite)”。--out-dir会改变一次性命名规则输出变为image_1.ext、image_2.ext……见 _build_output_paths。降采样副本使用默认后缀-web可用--downscale-suffix覆盖若后缀不以-或_开头会自动补-见_derive_downscale_pathimage_gen.py。默认一次性输出路径为output/imagegen/output.png源码常量DEFAULT_OUTPUT_PATH。降采样实现细节_downscale_image_bytesimage_gen.py依赖 Pillow按--downscale-max-dim计算等比缩放min(1.0, max_dim / max(w, h))使用 LANCZOS 重采样输出为 JPEG 时若原图带透明通道RGBA/LA会先以白色背景合成再转 RGB。常见配方Common Recipes配方一带增强字段的生成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默认开启可用--no-augment关闭会把--use-case、--scene、--subject、--style、--composition、--lighting、--palette、--materials、--text、--constraints、--negative等字段组织成结构化分节文本。实现见 _augment_prompt_fields依次拼接Use case:、Primary request:、Scene/background:、Subject:、Style/medium:、Composition/framing:、Lighting/mood:、Color palette:、Materials/textures:、Text (verbatim): ...、Constraints:、Avoid:各标签行仅有值的字段才会出现。配方二生成 网页快速加载的降采样副本python $IMAGE_GEN generate \ --prompt A cozy alpine cabin at dawn \ --size 1024x1024 \ --downscale-max-dim 1024 \ --out output/imagegen/alpine-cabin.png配方三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否则main()直接报错image_gen.py。--concurrency控制并发度默认5DEFAULT_CONCURRENCY合法范围 1–25image_gen.py实现基于asyncio.Semaphore。JSONL 每行一个任务支持按任务覆盖size、quality、background、output_format、output_compression、moderation、n、model、out以及提示词增强字段use_case、scene、subject、style、composition、lighting、palette、materials、text、constraints、negative也可放在fields子对象中。每行还支持#注释行与空行跳过任务可为字符串仅 prompt或 JSON 对象见_normalize_job/_read_jobs_jsonlimage_gen.py。单行 JSON 解析失败会报告具体行号任务总数上限为 500MAX_BATCH_JOBS。批量模式下任务级out被当作--out-dir下的文件名处理见_job_output_pathsimage_gen.py未指定out时默认命名规则为{序号:03d}-{提示词slug}{扩展名}slug 取提示词前 80 字符、小写并转连字符、最长 60 字符。单次批量还支持--n同一提示词出多个变体与--max-attempts默认 3合法范围 1–10与--fail-fast。重试逻辑_generate_one_with_retriesimage_gen.py只对瞬时错误429 限流、超时、连接重置退避重试退避时间优先取异常中的retry_after否则按min(60, 2**attempt)指数退避非瞬时错误直接抛出。--fail-fast开启时任一任务失败即终止并取消其余任务image_gen.py。语义区分--n是针对同一个提示词生成多个变体generate-batch是针对许多不同提示词的批量。两者可组合使用。CLI 参数速查与校验规则支持的尺寸1024x1024、1536x1024、1024x1536或autoALLOWED_SIZES默认1024x1024。输出格式与透明背景--output-formatpng默认、jpeg、webpjpg会被归一化为jpeg见_normalize_output_formatimage_gen.py。透明背景--background transparent要求输出格式为png或webp否则_validate_transparency直接报错image_gen.py。--background取值transparent|opaque|auto它控制输出透明度行为与提示词里描述的视觉场景/背景scene/backdrop不是一回事。其他受支持的参数--prompt-file与--prompt二选一_read_prompt会拒绝同时传入、--output-compression0–100仅 jpeg/webp 有效、--moderationauto默认 /low、--max-attempts、--fail-fast、--force、--no-augment、--n1–10。main()中还会统一校验--n范围 1–10、--concurrency范围 1–25、--max-attempts范围 1–10、--output-compression范围 0–100、--downscale-max-dim 1、模型必须为gpt-image-*、尺寸与质量必须在白名单内image_gen.py。边界与限制来自 image-api.md输入图与掩码均需小于 50MB编辑端点最多支持 16 张输入图。大尺寸 高质量会显著增加延迟与成本高input_fidelity会明显增加输入 token 用量。本 CLI 面向 GPT Image 模型gpt-image-1.5、gpt-image-1、gpt-image-1-mini不要套用旧的非 GPT 图像模型行为若某个选项不被所选模型支持导致失败可去掉该选项后手动重试。掩码为提示词引导精确形状不保证。使用护栏Guardrails按 cli.md 的要求环境激活正确后直接使用内置脚本python $IMAGE_GEN ...不要手写一次性 SDK 调用脚本。不要创建一次性运行器例如自建gen_images.py包装脚本除非用户明确要求自定义包装。绝不要修改scripts/image_gen.py。若发现缺失功能先询问用户再做任何事此规则同样写入 SKILL.md 与脚本头部文档。深入源码三条执行链路generate 链路_generate()image_gen.py→ 读取/增强提示词 → 组装 payloadmodel/prompt/n/size/quality/background/output_format/output_compression/moderation空值剔除→ 校验透明度 → 计算输出路径 → dry-run 打印请求或调用client.images.generate→ 解码b64_json写盘并可选降采样。edit 链路_edit()image_gen.py→ 校验图片与掩码 → 组装 payload额外含input_fidelity→ 通过_FileBundle/_SingleFile上下文管理器以二进制模式打开输入文件多图传列表、单图传单文件对象→client.images.edit(**request)。batch 链路_run_generate_batch()image_gen.py→ 读取 JSONL → 基础 payload 任务级覆盖合并_merge_non_null任务字段优先、非空才覆盖→ 按并发信号量调度 asyncio 任务 → 每任务独立重试与写盘。此外脚本把增强字段定义为 11 个可选参数_fields_from_argsimage_gen.py批量模式下命令行字段作为“基础字段”与 JSONL 中任务级字段合并任务级字段优先级更高——这解释了 cli.md 中“per-job overrides are supported”的实现原理。关联参考文档API 参数速查CLI 回退模式references/image-api.md两种顶层模式共享的提示词示例[references/sample-prompts.md网络/沙箱说明CLI 回退模式references/codex-network.md共享提示词原则references/prompting.md技能主文档与依赖安装SKILL.md本 CLI 的实现源码scripts/image_gen.py需要再次强调以上全部为fallback CLI 专属的执行控制面quality、input_fidelity、显式掩码、background、output_format与输出路径等均不是内置image_gen工具的参数。正常使用请始终以内置image_gen工具为默认路径仅在用户显式要求 CLI 模式时按本文操作。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
