imagegen

imagegen

概要：Codex エージェントに組み込まれた画像生成機能で画像を作成します。この Skill が担当するのは、要件を適切なプロンプトにする、コマンドを実行する、品質を確認する、圧縮する、プロジェクト内の適切なディレクトリに配置する、の5つだけです。

画像生成はCLI のサブコマンドではありません（codex image はありません。codex exec --image は画像を入力として添付するものです）。Codex エージェントに組み込まれたツール image_gen です。codex --help でフラグを探し、見つからないから「画像を生成できない」と結論づけないでください。その結論は間違いです。必要な画像を説明すれば、エージェントが適切な方法を選びます。

起動コマンド

mkdir -p <outdir>                                # 先建目录，提示词里写它的绝对路径
cat <outdir>/prompt.md | codex exec --skip-git-repo-check \
  --config model_reasoning_effort="medium" \
  --sandbox danger-full-access \
  -C <outdir> -o <outdir>/final.md 2>/dev/null

要点	説明
バックグラウンドで実行	Bash の run_in_background: true を使います。画像2枚で約2～3分、セット画像はさらに時間がかかります。完了通知を待ち、ポーリングしないでください。注意：必ずメインスレッドから呼び出してください（subagent からではありません）。subagent で run_in_background を使うと、通知待ちで park した後、harness にアイドル状態と判定されて終了され、通知が届かなくなります
--sandbox danger-full-access	画像生成にはネットワークが必要です。このフラグの確認が必要かどうかは、現在のマシンの許可設定によります。常設の許可があればそのまま実行し、なければそのマシンのルールに従って一度確認してください。どちらの場合も、起動コマンドの行に使用した sandbox を明記してください
-o <outdir>/final.md	最終レポートをファイルに書き込みます。パスと方法はここから確認してください。stdout は進捗状況のノイズなので、解析しないでください
2>/dev/null	stderr の思考ストリームを抑制します。Codex 自体をデバッグするときだけ外してください
effort	medium で十分です。これは推論タスクではありません
-m を渡さない	~/.codex/config.toml のデフォルトモデルを使用します。ユーザーから指定があった場合のみ変更してください
元画像の場所	Codex が image_gen を実行するたびに、元画像は ~/.codex/generated_images/<session-id>/exec-*.png に保存されます（1枚あたり0.7～1.5 MB）。出力ディレクトリにあるのは後処理済みの画像です。元画像が必要な場合は、そちらから取得してください

codex --version が失敗する、または起動直後に終了する場合は、まず codex doctor を実行し、事実をそのまま報告してください。むやみに再試行しないでください。

プロンプトの書き方

prompt.md には以下の6項目を必ず含めてください。1つでも欠けると、それに起因する問題が発生します。

1. 出力ディレクトリの絶対パス（mkdir -p 済みのもの）。
2. 画像ごとの番号：正確なファイル名、具体的な説明、ピクセルサイズ／アスペクト比。
3. 共通のスタイルブロック：画風、背景、hex カラーパレット、光、レンズ。セット画像の一貫性を保つために使います。
4. No text, no letters, no logos, no watermarks. 生成される文字はほぼ必ず崩れます。英語以外の画面ではなおさら誤字になります。文字は後から HTML/CSS で重ねてください。
5. 代替手段の条件：If you genuinely cannot generate images, say so plainly. Do not substitute placeholders, ASCII art, solid rectangles, or images downloaded from the web.
6. 報告事項：各ファイルの絶対パス、実際のピクセル数、バイト数、alpha の有無、使用した方法（ツール／モデル、ローカルでの後処理の有無）。

透明画像の場合は、必ず true alpha, not a white/dark square と記載してください。実際のテストでは、Codex はこの指示で自分の出力を確認し、初版に焼き込んでしまった背景色を自分で修正しました。

さらに、よく使う予備指示を追加してください：If the exact size is unsupported, generate the nearest aspect and resize locally (sips / PIL) to the exact pixels; keep alpha for transparent items.

完全な例（マスコット + og:image の2枚セット）

Generate two images with your built-in image generation tool and save them to:
<outdir absolute path>/

Shared style: palette #2563EB (primary) #F59E0B (accent) #0F172A (ink) #F8FAFC (paper).
No text, no letters, no logos, no watermarks anywhere.

1. `mascot-logo.png` — 1024x1024, transparent background PNG (true alpha, not a white square).
   A friendly round owl holding a tiny wrench. Flat vector style, bold clean shapes,
   2-3 flat tones per element, no gradients, no drop shadows. Occupies 75-80% of the
   frame, centered, exclude the wrench from that measure.

2. `og-image.png` — 1200x630 (1.91:1), opaque. Photorealistic editorial photo: a person
   in their late twenties at a wooden desk in front of a laptop, soft window light from
   the left, shallow depth of field, calm home office, mug and small plant. Eye-level,
   subject on the left so the right third is clean negative space. Laptop screen is a
   soft blurred blue-white glow, nothing readable.

Rules: if you genuinely cannot generate images, say so plainly — no placeholders, ASCII
art, solid rectangles, or web downloads. If the exact size is unsupported, generate the
nearest aspect and resize locally (sips / PIL); keep alpha for the mascot.
Report per file: absolute path, actual pixels, bytes, alpha yes/no, method used.

用途別テンプレート

用途	サイズ／形式	スタイルブロックの要点	必須の制約
ロゴ／favicon の元画像	1024×1024 の透明 PNG。その後 sips -Z で 512／192／180／32／16 に縮小	flat vector、太くはっきりしたシルエット、2～3色調、グラデーションなし	主体を画像の75～80％にする。16px でも見分けられること（単純な形にして、細部に頼らない）。文字なし
マスコット	1024×1024 の透明 PNG。セットの場合は、同じプロンプトで複数のポーズを生成	上記に加え、頭身比、目の直径÷頭の幅などの特徴を数値化	種、道具（1つだけ）、配色をすべて明確に指定します。道具は占有率に含めません
og:image／共有画像	1200×630、不透明。ページごとに1枚ずつ用意	主体を片側に寄せ、反対側にきれいな余白を残す（タイトルは後から重ねる）	120px に縮小しても主体を判別できること。文字なし。サイト全体で共用しないこと
記事ページの挿絵	1600×900 または 4:3。JPEG／WebP	サイトのカラーパレットに合わせる。同じサイトでは同じ画風にする	そのページのターゲットキーワードと意味的に関連づける（キーワードではなく、場面を指定する）
ユーザーの利用場面／人物写真	1600×1067（3:2）または 1200×630	フォトリアリスティックなエディトリアル写真、自然な窓からの光、浅い被写界深度、35～50mm の画角	年齢層、動作、環境、光の方向、構図を指定します。画面の内容は「ぼんやり光っていて、読める文字はない」とします。実在する人物の名前は使いません
手描き／クレヨン／水彩のイラスト	1600×1200 または正方形。紙の質感を含める場合は不透明	textured paper にクレヨンで描いた表現／ラフな水彩、筆跡が見える、限られた色数	紙の色と質感、線の太さ、余白の比率を指定します
ポスター／映画のような画面	縦 2:3（1000×1500）または横 21:9	シネマティック、アナモルフィック、ボリューメトリックライト、カラーグレーディングの色を hex で2色指定	文字用の空間を空けます。主体の位置を明確に指定します（三分割法のどの区画か）

サイズとアスペクト比を明記してください。モデルが正確なピクセル数を出せない場合は、ローカルでリサイズします。「圧縮と保存」を参照してください。

セット画像の一貫性

• 1つのプロンプトファイルでセット全体を生成し、共通のスタイルブロックを先頭に置いて、画像ごとに違いだけを記述します。分けて実行する場合は、同じスタイルブロックをそのままコピーしてください。
• カラーパレットは hex で明確に指定し、「青系」とは書かないでください。同じセット内では、キャラクターの比率、線幅、紙の質感も数値で指定します。
• 形容詞（「もっと日本風に」など）だけでは限界があります。頭身比、目の直径÷頭の幅、線幅÷画像幅、HSV の彩度範囲、余白率など、測定できるパラメーターに置き換えてください。参考画像と生成画像を同じスクリプトで測定し、「パラメーター | 参考範囲 | こちらの値 | 判定」の表を作ると、感覚的な判断を項目ごとに修正できるチェックリストにできます。
• プロンプトは対象言語で書いても構いません（n=3 のブラインド評価では対象言語が優勢でしたが、有意差には至りませんでした）。実際に効果があると確認できているのは、視覚的な制約を数値で指定することです。

品質確認：3段階のチェックで、それぞれ異なる問題を検出

出典：codex/references/image-experiments.md の「セット画像の検収」。2026-08-22 に16枚のキャラクター画像を一度に検証した記録では、3段階それぞれで異なる欠陥が見つかりました。

まず Read で画像を1枚ずつ開いて確認してください。その後に、以下の3段階のチェックを行います。確認していない画像をページに組み込んではいけません。3段階すべてが必須です。1つでも欠けると、その種類の問題を見逃します。

1. コンタクトシート（構図の偏りを検出）：すべての画像を幅120pxに縮小し、横に並べて1枚にします。これは結果ページ／共有カードでの実際の表示サイズです。フルサイズでは見栄えがよくても、サムネイルに椅子しか残らない画像は、この方法でしか見つけられません。 sips -Z 120 in.png --out thumbs/in.png
2. alpha バウンディングボックスの占有率（「大きさが十分か」を数値化）：

   from PIL import Image
   im = Image.open(f).convert('RGBA'); bb = im.getchannel('A').getbbox()
   frac = (bb[2]-bb[0])*(bb[3]-bb[1]) / (im.width*im.height)   # 目标 0.75–0.80
   

   6枚セットを実測したところ、占有率は41～66％でした。どの画像も目標を満たさず、最大と最小で1.6倍の差がありました。並べて見ただけでは「少しばらついている」と感じる程度です。プロンプトには占有率だけでなく、道具は占有率に含めないことも明記してください。
3. 独立したブラインド評価（画風とルール遵守を確認する、最も省略されやすい段階）：ペアごとの結果をランダムに並べ替えて pairN-A/B とし、対応表はプロジェクトディレクトリの外に置きます。生成に関与していないエージェントを選んで評価させ、「違いが分からない」という判定も許容することを明示します。ブラインドでない評価の結果が、ブラインド評価によってセット全体で覆されたことがあります。原因は、余分な道具が追加されていたことでした。

参考画像／ムードボード

スタイル自体は著作権で保護されないため、参考画像を使うのはデザイン業界では一般的です。制御するポイントは入力ではなく、出力側です。

1. 参考画像は複数枚（異なる出典から10枚以上を集めてムードボードにする）使い、1枚だけにしないでください。1枚だけだと、元画像に似たものになりやすいためです。
2. 参考画像から伝えるのは質感（線、塗り、頭身比）だけにします。主体はこちらで明確に指定します。種、道具、ポーズ、配色を指定してください。
3. 生成後、参考画像と並べて類似性を確認します。「既存のキャラクターだと思われる可能性はないか」と確認し、似ている場合は画風ではなく主体の特徴を変えて再生成します。
4. プロンプトで著作権保護されたキャラクターの名前や、"in the style of X" を指定しないでください。参考画像から必要な情報はすでに伝わっているため、名前を出しても効果は増えず、リスクだけが高まります。

压缩与落盘

原图约 1 MB/张 PNG，不压缩不许进仓库。

sips -s format jpeg -s formatOptions 82 in.png --out out.jpg   # 不透明图：JPEG，4 MB 一套压到 1 MB 内
cwebp -q 82 in.png -o out.webp                                  # 页内用 WebP（透明也保留）
cwebp -q 82 -alpha_q 100 mascot.png -o mascot.webp              # 透明主体，alpha 无损
sips -Z 512 logo.png --out icon-512.png                         # 等比缩最长边
sips -z 630 1200 og.png --out og.png                            # 精确到像素（先高后宽）

透明没做出来、或主体占比不达标时，用 ImageMagick 二次处理（先 which magick，没有就 brew install imagemagick）：

magick in.png -fuzz 8% -transparent '#0F172A' out.png          # 纯色底抠透明（换成实际底色 hex）
magick in.png -trim +repage -resize 800x800 -gravity center \
  -background none -extent 1024x1024 out.png                    # 裁掉空边，主体缩到约 78% 再居中回 1024²
magick out.png -format 'alpha_min=%[fx:minima.a] colors=%k\n' info:   # alpha_min 必须是 0 才算真透明

素材	保留格式	放哪（示例路径）
logo / 图标集	透明 PNG 源 + SVG（如有）；导出 512/192/180/32/16	<project>/public/brand/，manifest.json 逐个真实引用
og:image	PNG 或 JPEG（WhatsApp/FB 预览爬虫对 WebP 不稳；rankup/references/seo-experiences.md 2026-07-18）	<project>/public/og/<page-slug>.png，一页一张
页内配图 / 场景图	WebP（同图 175 KB→56 KB），<img> 写真实 width/height	<project>/public/images/<section>/
原始生成物与 prompt.md	原样留档，不进 public/	<project>/design/imagegen/<batch>/

• 多文件循环、等待轮询一律用 python3 heredoc 驱动：Claude Code 的 Bash tool 里裸 for f in *.png; do …; done 和 until [ -f x ]; do sleep 2; done 可能报 parse error near 'done'（2026-09-02 在一台 macOS zsh 环境实测），用 heredoc 最稳。
• 亮底插画进深色主题要压暗：filter: brightness(.84) saturate(.92)。
• 页面接线后 curl -I 每张图 200；仓库结构迁移后 favicon/og 静默 404 是踩过的坑。

与 rankup 的关系

• rankup/SKILL.md 段 3（建站）硬规则和「一句话落到哪一段」表都指到 /imagegen：网站需要任何视觉素材就来这里真实生成。
• 段 3 红线：任何页面不得出现占位图（灰块、placeholder、模板示例图），Google 据此判垃圾站、整站连坐；段 4 硬规则：每页独立 og:image 且必须有图，≥1200px 宽，全站共用一张不通过。两条叠加，没有生成能力就只剩占位一条路——所以出图是建站流程的固定环节，不是可选美化。
• 图做完回 rankup 走闸门：checklists.md 段 3「无占位红线」、段 4「每页独立 title/description/og:image 且有图」、闸门 0 图标全集与 manifest.json 引用全真实、标记经 16px 实测。
• og 双格式：og:image / twitter:image 用 PNG/JPEG，页内 <img>、JSON-LD image、image-sitemap 用 WebP。

反模式

• 翻 codex --help 找不到 image flag 就宣布"Codex 不能生图"。
• 前台跑 codex exec 让用户干等；或紧密轮询后台 shell。
• 有常设授权的机器上还为 --sandbox danger-full-access 反复请示——按该机器的规则处理一次，启动行披露即可。
• 提示词里让模型画文字、标语、品牌名。
• 没用 Read 打开过就把图接进页面；或把未压缩的多 MB 原图提交进仓库。
• 一页一图全站共用同一张 og:image；或先塞一张灰块"以后再换"。
• 用单张他人作品做参考并在提示词里点名角色。
• 只做一两道验收就往下走；非盲判断直接写进结论。
• 为"省配额"缩小批量或不敢重生成——先看当前账号的计划；额度充足时第一版差一点就再跑，不要拿猜测的配额限制自己。
• 在 subagent 内部用 run_in_background: true 跑 codex exec——subagent park 后 harness 判定其空闲并终止，完成通知永远送不到，图生成了但没人收。必须从主线程跑 codex exec（Bash 的 run_in_background: true），主线程能正确接收完成通知；或者 subagent 内改用前台同步等待（但会占用 subagent 上下文数分钟）。2026-09-11 同一批任务因此重试三次。

已验证（2026-09-02，codex-cli 0.149.0）

• 链路：两张图一套（1024² 透明吉祥物 + 1200×630 真人场景 og:image），命令即上文模板，-o final.md 拿最终报告。exit 0，无报错，总耗时 302 s（约 5 分钟）。
• Codex 用的方法：内置 image_gen 工具（日志里出现 gpt-image-1.5 / gpt-image-2 字样，Codex 自报「具体模型名未公开」）；本轮共调了 9 次，原图全部落在 ~/.codex/generated_images/<session-id>/exec-*.png，每张 0.7–1.5 MB。最终文件是它用 ImageMagick（magick，本机 7.1.2）后处理得到的：吉祥物 resize → -remap 锁定提示词里的四个 hex → alpha 提取；og 图轻微居中裁切缩到精确 1200×630。要没被后处理过的原图去 generated_images/ 拿。
• 结果：og-image.png 1200×630 RGB 757 KB，构图、光线、屏幕模糊无字全部按要求；mascot-logo.png 1024×1024 RGBA 33 KB（四色量化），真透明——57% 像素 alpha=0，alpha 极值 (0,255)。
• 透明背景有一段弯路：跑到约 3.5 分钟时目录里已有一版 mascot-logo.png，alpha 全 255、深蓝底被烤进去了；Codex 自己又跑了两轮才在第 5 分钟做出真透明。教训两条：① final.md / 退出码出来之前别量图，中间态会误判；② 提示词里 true alpha, not a white/dark square 这句要写，它确实靠这句自检。若最终仍不透明，按「压缩与落盘」的 ImageMagick 抠底命令二次处理，不要写成功。
• 没达标的一项：吉祥物 alpha 包围盒占比 0.62，提示词写了 75–80% 仍不够（与 2026-08-22 那批 41%–66% 同一现象）。修法在「压缩与落盘」：-trim 后按目标占比 -resize 再 -extent 回 1024²。
• 压缩实测：og PNG 757 KB → sips JPEG q82 92 KB → cwebp q82 27 KB；四色量化的透明 PNG 33 KB → WebP 反而 48 KB，已量化的扁平透明 PNG 直接用，不转 WebP。
• 接触印相 sips -Z 120 两张均可辨主体；盲评本次未做（单张无对照）。