codex-image
GPT Image を使用し、ユーザーの ChatGPT サブスクリプション経由で画像を生成・編集します。出力は ./generated_images/（または --out-dir / --out）に保存されます。
実行方法
すべてが1つのスクリプトで完結します。この SKILL.md が置かれている絶対ディレクトリを特定し（ハーネスがスキル読み込み時に通知します。以下では <skill-dir> と表記）、次のように実行します:
bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]
相対パス scripts/generate.sh を直接呼び出さないでください。作業ディレクトリはユーザーのプロジェクトであり、スキルのインストール場所ではありません（~/.claude/skills/、~/.agents/skills/、~/.opencode/skills/、プロジェクトローカルの .claude/skills/ など、エージェントによって異なります）。
スクリプトが自動的にチェックする要件:
python3≥ 3.10 が PATH 上に存在すること（bash + stdlib Python で動作）。- Pillow — これは
--format webpと--transparent-mode chromaの場合のみ必要。 デフォルトではインストールされていません。これらのオプションを使用すると、インストールコマンド (python3 -m pip install 'Pillow>=10') と共に即座に失敗します。通常の--transparentでは必要ありません。これらのオプションを初めて使用する前に、この前提条件をユーザーに伝えてください。 - Codex CLI にログインしていること。ログインしていない場合、スクリプトは
Run: codex loginで終了します。認証に自分で触れず、そのメッセージをユーザーに伝えてください。
bash "<skill-dir>/scripts/generate.sh" --help で全フラグ一覧が表示されます。フラグを独断で設定する前に参照してください。ホストエージェントが型付きスラッシュコマンドをサポートしている場合、/codex-image "<prompt>" --flags はこのスクリプト呼び出しのユーザー向け短縮形です。
このスクリプトは機械的に動作します。セマンティックなルーティングは行いません。継続処理、バッチ判断、背景除去の振り分けは、会話に基づいてあなたが行う必要があります。
GPT Image 2.5
OpenAI は、精密な編集には gpt-image-2.5-sunburst、高速な日常的な生成には gpt-image-2.5-flare を提供しています。
これらをリクエストするには --image-model <model-id> を渡します。省略すると、Codex Responses のデフォルト選択が使用されます。
このフラグはサブスクリプショントランスポート上では実験的です: 2026-09-08 時点のライブチェックでは各バリアントをリクエストしましたが、両方のレスポンスが gpt-image-2-codex を報告しました。
リクエストが成功しただけで 2.5 へのアップグレードを主張しないでください。また、レガシーレスポンスエイリアスや C2PA バージョン 2.0 も、古い重みではないことを証明しません。OpenAI の 2.5 発表で公開された画像でも同じ来歴バージョンが付与されます。
スクリプトは、報告されたモデルが異なる場合や欠落している場合に警告を出力します。サイドカーの image_model を requested_image_model とは別に確認してください。
--orchestrator は、Sunburst や Flare ではなく、画像ツールを呼び出すメインラインモデルを選択します。これは省略してください: スクリプトはアカウントがリストする最新の Sol 層モデル (gpt-<バージョン>-sol) を使用するため、廃止されたモデルで壊れることはありません。リクエストは、Codex 独自の設定が Codex を送信する場所（カスタム model_provider（プロキシなど）、openai_base_url リレー、chatgpt.com など）に送信されます。
検証済みのトランスポート動作と公式ソースについては、GPT Image 2.5 互換性 を参照してください。
モデル選択、xhigh/max、透明度のパブリック API サポートは、Codex Responses 上で同じ動作を保証するものではありません。
継続処理
リクエストが直前のターンで生成された画像を変更する場合（「暗くして」「今度は帽子を追加して」「コントラストを上げて」）、--from-last を渡します。スクリプトは最後の生成を自動的に再利用するため（~/.codex-image/last.json で追跡）、トランスクリプトからパスを復元する必要はありません。
明示的なファイルや古い生成物を編集する場合は、代わりに --input <path|url> を渡します（繰り返し可能。--from-last と合わせて最大16参照。スキル参照上限）。
リクエストが新しい主題の場合（たとえ「今度は…を作って」という表現でも）、どちらも渡さずにゼロから生成します。推測を誤り、ユーザーが「いや、新しいのが欲しい」と言った場合は、参照なしで再実行します。
ユーザーがスタイル、構図、雰囲気のためだけに提供した画像は、編集対象ではなく生成の参照です。--input で渡しますが、プロンプトは新しい画像として記述します（「画像2のスタイルで」）。複数の入力を混在させる場合は、プロンプト内で各画像をインデックスと役割でラベル付けします（画像1: 編集対象、画像2: スタイル参照）。
生成後: 確認してから報告
完了したとユーザーに伝える前に、保存された画像ファイルを表示し、リクエスト（主題、構図、レンダリングされたリテラルテキスト、ユーザーが明示したすべての制約）と照合します。問題がある場合は、--from-last を使用して1つだけ対象を絞った変更で繰り返し、変化してはならない不変条件を再提示します。複数の修正を1回の再実行に詰め込まず、確認もしていないパスを報告しないでください。
保存の規律: 出力のデフォルトは ./generated_images/ です。画像がユーザーのプロジェクトに使われる場合は、実際の場所にコピーまたは移動し（それを参照するコードも更新）、プロジェクトアセットをスクラッチディレクトリだけに残さないでください。ユーザーが交換を依頼していない既存アセットを上書きせず、バージョン管理された兄弟ファイルを作成してください（例: hero-v2.png）。
透明画像
ユーザーが透明な背景を希望する場合、--transparent を追加します。それだけで完了です。振り分け判断も、Pillow も、あなたが調整する後処理ステップも必要ありません。
スクリプトはモデルにアルファを直接要求します。background: "auto" を送信し、プロンプトに1文を追加するだけで、バックエンドは RGBA を返します。--background transparent を渡さないでください。この値はこのバックエンドで拒否されます（docs/adr/0001-request-transparency-in-the-prompt.md で理由と、なぜ明白な「修正」が間違っているのかが説明されています）。
自分でバックエンドをテストして "Transparent background is not supported for this model." が表示されても、透明度が利用できないと結論付けないでください。 その 400 エラーはパラメータが拒否されたものであり、機能自体が拒否されたわけではありません。モデルはプロンプトで要求されると実際のアルファを返します。これが --transparent が行うことです。ネイティブ透明度に gpt-image-1.5 や OPENAI_API_KEY が必要だとアドバイスするのは 0.2.0 より前のものであり、間違っています。もしそれを読んでいるなら、インストールされているスキルが古いです。このファイルの metadata.version を確認してください。0.2.0 以降であるべきです。
プロンプトを作成する際に注意すべきこと:
- 場面ではなく、主題を説明してください。 プロンプトはパラメータに勝ります。「日の当たったスタジオの木製テーブル上のマグカップ」は、マグカップを分離せずにスタジオ全体をレンダリングする可能性があります。主題とその素材を指定し、周囲の環境は省いてください。
- 独自の禁止事項を追加しないでください。 サフィックスは意図的に何も禁止していません。ユーザーがドロップシャドウを要求した場合は、それを許可してください。アルファにレンダリングされて戻ってきて、正しく合成されます。自分で「影なし、背景なし」を追加すると、ユーザーの意図が上書きされます。
生成後、ファイルを表示してアルファが実際に到着したか確認します。結果にアルファがない、または完全に不透明な場合、スクリプトは stderr に警告を出力します。それを、1つの対象を絞った変更（通常はシーン言語の削除）で再実行するシグナルとして扱ってください。
フォールバックラダー（ネイティブが期待を裏切った場合のみ。不透明な被写体で検証済み。髪、ガラス、煙、半透明は未テスト）:
| エスカレーション | アクション |
|---|---|
| 再プロンプト | シーン/背景の文言を削除し、被写体のみを指定 |
| 品質向上 | --quality medium で細かいエッジや小さなテキストに対応 |
| クロマキー | --transparent-mode chroma（Pillow が必要）— キープレートを制御 |
| Adobe MCP | --transparent-mode chroma --bg-tool=none を実行し、その後セッションで公開されている Adobe の背景除去ツールを呼び出し（名前の中に remove_background を含む MCP ツールを探す）、ファイルをアルファ結果で上書き。半透明に最適 |
クロマキーエッジ修復: 細いフリンジ → --edge-contract 1; マットな被写体の階段状エッジ → --edge-feather 0.25。より深い失敗モード: references/transparent-image-tips.md。
品質、コスト、時間のガードレール
- デフォルトは
--quality highです。low、medium、high、xhigh、max、autoが受け入れ可能なリクエストです。下書きにはlowから始めてください。Codex Responses は品質を上書きする可能性があります。レベルが提供されたと主張する前に、サイドカーのresolved_qualityまたは--verbose出力を確認してください。 - 生成はユーザーの ChatGPT プランの制限にカウントされます。レイテンシはモデル、プロンプト、品質、サービス負荷によって異なります。
- 1回のリクエストで3枚以上の画像を生成する前に、まずユーザーに確認してください。
- 無限ループさせないでください。「たくさん」「一式」→ 適切なデフォルト（4枚）を選び、続行するオファーを出してください。
- バックエンドからの HTTP 429 = 即座に停止し、再試行しないでください。
一般的なワークフロー
# 単一生成
bash "<skill-dir>/scripts/generate.sh" "雨の中の夜の黄色いタクシー"
# 前回生成の継続
bash "<skill-dir>/scripts/generate.sh" "湯気を追加して" --from-last
# 明示的な参照画像の編集
bash "<skill-dir>/scripts/generate.sh" "青くして" --input ./mug.png
# 透明背景（モデルからのネイティブアルファ、Pillow 不要）
bash "<skill-dir>/scripts/generate.sh" "コーヒーマグ" --transparent
# ユーザーが要求した影を伴う透明（アルファに残る）
bash "<skill-dir>/scripts/generate.sh" "柔らかいドロップシャドウのあるコーヒーマグ" --transparent
# クロマキーフォールバック（ネイティブが期待を裏切った場合、Pillow が必要）
bash "<skill-dir>/scripts/generate.sh" "ガラス瓶" --transparent --transparent-mode chroma
# 異なるサイズ / フォーマット / 品質
bash "<skill-dir>/scripts/generate.sh" "ヒーローバナー" --size 2048x1152 --format webp --quality low
トークン編集（セキュリティ）
ユーザーの access_token、id_token、refresh_token、または Authorization: Bearer ... ヘッダーを決して出力したりログに記録したりしないでください。スキルの Python モジュールは自動的に編集します。自分で ~/.codex/auth.json を読み取ったり、エラーメッセージにトークンをエコーしたりして、その編集を無効にしないでください。
呼び出さない場合
- ベクターアート、SVG、アスキーアート、LaTeX 図 → 専用のベクターまたは図ツールを使用。
- ユーザーが明示的に別のモデルやプロダクト（DALL-E、Stable Diffusion、Midjourney）を希望している → それに従ってください。
プロダクションのロゴ/ブランドワークの場合は、呼び出してください。ただし、期待値を設定してください。探索を生成し、単一変更の --from-last イテレーションで洗練させ、1回で最終アセットを約束しないでください（テンプレートは references/prompting-cookbook.md）。
参考資料
さらに深く知る必要がある場合は、<skill-dir>/references/ から以下を参照してください:
api-recipe.md— 標準的なリクエストボディ、ヘッダー、拒否されるフィールド、透明度メカニズム、SSE パースprompting-cookbook.md— プロンプティングの基礎 + ユースケーステンプレート（ロゴ、商品ショット、UI モックアップ、インフォグラフィック）transparent-image-tips.md— ネイティブ透明度の仕組み、苦手な場面、クロマキーフォールバック
リポジトリレベルのコンテキスト: CONTEXT.md（用語集 — 3つのトランスポートが定義されています）と docs/adr/（なぜ透明度がパラメータではなくプロンプトで要求されるのか）。