| name | codex-image-gen |
| description | 用 Codex(订阅账号,gpt-image-2)生成或编辑图片,特长是用参考图锁定角色/风格一致性。当用户显式点名用 Codex 出图,或需要参考图锁角色/风格的场景时使用。通过 `codex exec` 调内置 image_gen 出图,产物存为 PNG。通用生图/程序化出图未点名具体后端时,由 `media-gen` 统一路由选后端,不在此抢默认。 |
Codex 生图
借用本机已登录的 Codex 订阅账号,经 codex exec 调用其内置 image_gen 工具(gpt-image-2)出图。Claude Code 自身无生图能力,这个 skill 就是那座桥:你写好提示词,它出 PNG。
何时用
- 用户要为文章 / 文档 / 网页生成插图、配图、封面、图标、Banner、占位图等。
- 用户要基于参考图做角色一致的系列图(给
--ref)。
- 未指定走 ComfyUI / 即梦等其他后端时,这是默认出图后端。
怎么用
只调一个脚本(已可执行):
bash ~/.claude/skills/codex-image-gen/scripts/gen-image.sh \
--prompt "画面的具体描述" \
--out "目标路径/名字.png" \
[--size 16:9] \
[--ref 参考图1.png] [--ref 参考图2.png] \
[--dir 工作目录]
- 脚本成功后会把最终 PNG 路径打到 stdout;失败退出码非零。
- 产物同时保留在
~/.codex/generated_images/,脚本会把它拷到 --out。
- 多张图就多次调用,一次一张(别让模型把多图拼进一张)。
参数要点
| 参数 | 说明 |
|---|
--prompt | 必填。越具体越好:主体、风格、构图、背景、配色、留白。英文对模型更稳,中文也支持。 |
--out | 必填。保存路径,父目录自动建。 |
--size | 宽高比 / 尺寸:16:9、1:1、1536x1024 等。不传由模型自定。 |
--ref | 参考图,可重复。做系列图保持同一角色 / 同一画风时务必带上,一致性远好于纯文字描述。 |
--dir | codex 工作目录,默认取 --out 父目录,一般无需指定。 |
写提示词的几条
- 一张图只讲一个主体 / 一个结构,别堆。
- 指明风格(手绘线稿 / 扁平插画 / 3D / 像素 / 水彩…)、背景(纯白 / 透明 / 渐变)、配色、留白。
- 要文字标注就在 prompt 里写清要出现的短文字(模型出长文/多字容易错)。
- 透明背景:prompt 里写 "transparent background" 或 "on a solid green background for chroma key"。
- 出图后用 Read 工具看一眼成品,不满意就改 prompt 重生成,或追加
--ref 上一张 局部调整。
出图必留痕（sidecar 约定 · 260712 素材体系）
每张进媒体工作流的产物都要留痕：素材落分类目录（内容级 素材/{真材料,生图,精灵}/、频道级 风格卡/素材库/{插画,装置}/），出图成功后往本类 _meta/<名>.json 写 sidecar——新对话/新频道零人工记忆，asset-index 扫描即得（prompt 直接成检索描述符），qc 可 ls 对账（每文件 ↔ 一条 sidecar）。
~/.venvs/current/bin/python ~/.claude/skills/codex-image-gen/scripts/write_sidecar.py \
--out "素材/生图/shot-3.png" --prompt "刚才的完整提示词" --backend codex-image-gen \
[--aspect 16:9] [--ref shot-3] [--license original] [--washed true]
gen-image.sh 不内嵌此步——留痕由调用方/管线负责（编排素材步时调本 helper 补写）。- 幂等可重跑：已有 sidecar → 字段覆盖更新、
refs 去重追加、created 保留首次；产物不存在则拒写（不给不存在的东西记账）。
- 后端无关：图/视频/HTML/音频都能记（
--kind 缺省按扩展名自判），其它出图后端（gemini-gen / comfyui / media-gen 编排）同样可调本工具留痕。
批量出图（并发，多张时用这个）
要一次出很多张（系列配图、整套资产）时，不要串行一张张等——gen-image.sh 是单图工具（一次一张），并发交给批量入口 scripts/gen-batch.sh：
- 为每张图写一个 job 文件：文件名（去
.txt）= 输出图基名，内容 = 完整提示词。
jobs/01-topic.txt → 出 01-topic.png。
- 跑：
bash ~/.claude/skills/codex-image-gen/scripts/gen-batch.sh \
--jobs <jobs目录> --outdir <输出目录> \
[--concurrency 3] [--ref 定妆图.png] [--size 16:9]
- prompt 走文件传入，免命令行转义与长度限制；每个 job 输出独立路径，主路径并发安全；用 FIFO 信号量滚动并发，兼容 macOS 自带 bash 3.2。
--concurrency 先从 3 起：Codex 订阅有服务端速率限制，开太高可能整批被限流。遇报错就降到 1-2，失败的 job 单独重跑即可（已成功的不受影响）。- 系列图保持同一角色：所有 job 都带同一张
--ref 定妆图。
按层生成（分层素材协议·喂 video-master 分层镜）
给 layered-parallax（分层视差）/ layered-reveal（测绘揭示）出素材时，不生成一张整图再拆，而是源头按层生——生图无限额度下这是零分割误差、零补洞、风格零漂移的路线：
- style anchor：写一段风格锁（画风 / 色板 / 质感 / 禁用元素），贴在每个 prompt 顶部锁全组一致；有频道画风锁就从它生成。
- 布局参考图：先出一张完整构图（只用来定各元素位置关系，不进成片）。
- 背景板（
bg.png·不透明）：单独一张，"background only, no subject, low contrast"。
- 逐元素出层（每元素一张·全画布同尺寸）：主体 / 配角 / 道具各一张，纯 chroma 平底——prompt 写
isolated subject on a solid pure green background (#00FF00), no shadows, no reflections, positioned at <布局参考里的位置>；绿色主体换品红底 #FF00FF。Codex 内置 image_gen 不支持透明背景（请求透明会存成不透明 RGB），chroma 底是官方 imagegen skill 的标准解法。系列层全部 --ref 布局参考图（或前一层）锁风格与相对位置。
- 去底：
~/.venvs/current/bin/python ~/.claude/skills/codex-image-gen/scripts/strip_chroma.py in.png out.png（key 自动取边框中位色；--key green|magenta|#RRGGBB 可显式指定）。自带 despill 去溢色 + 收边 1px；stderr 报 kept_ratio 异常时肉眼核。
- 从一张定稿图衍生层（备路）：已有整图必须拆时，用 codex 编辑模式出两张——"remove the subject, keep only the background" + "keep only the subject, on solid green background"，风格零漂移。
产物命名约定：bg.png + layer-<序号>-<语义名>.png（如 layer-1-figure.png），全画布同尺寸（元素位置烘焙在图内），直接进引擎 public/images/<内容>/ 喂 scenes payload。
成本 & 前置
- 走订阅额度,不按张计费;每张约 1.5w–3w Codex token(agent token 计入 Codex 用量)。
- 依赖:
~/.codex/auth.json 已登录(本机已是订阅登录);codex 在 PATH(已全局安装),否则脚本自动退回 npx @openai/codex@latest。
和其它 skill 配合
- docsify-station-creator / wiki-creator:生成的图存进文档
assets/,需要公网 URL 时按你自己的 CDN 规约推到公网 CDN,markdown 里引用——站点运行时仍只引自托管资源。
- 要带固定 IP 角色出图:把角色设定写进 prompt + 用
--ref 喂角色参考图;后续若要做成专门的「IP 配图 skill」,可在本 skill 之上加一层风格/IP 参考(参考 ian-xiaohei 的 references 结构)。
