gpt-image-2-skill

プロバイダーごとの差異を隠す単一の CLI インターフェースを通じて、画像の生成と編集を行います。scripts/gpt_image_2_skill.cjs の Node ラッパーは、基盤となる Rust バイナリを解決し（環境変数による上書き → 同梱された Skill バイナリ → インストール済みバイナリ → Tauri App に同梱された CLI → リポジトリの cargo run → キャッシュ済みリリース → ブートストラップダウンロード）、すべてのフラグを転送します。glibc Linux では、リリースのブートストラップ時に GNU アーカイブを最初に試し、その後、サンドボックス用のフォールバックとして静的 musl アーカイブを試します。

このスキルを使用する場面

• 画像を生成または編集し、エージェントが解析できる構造化された結果を取得する場合。
• コマンドの形式を変えずに、OPENAI_API_KEY、OpenAI 互換のベース URL、Codex の auth.json を切り替える場合。
• CLI、App、Skill で同じデフォルトプロバイダーを使用できるよう、$CODEX_HOME/gpt-image-2-skill/config.json の共有プロバイダー設定を尊重する場合。
• 最終成果物として透明な PNG、マスク、最大 4K のカスタムサイズ、または生のリクエストボディが必要な場合。
• 最終 JSON を stdout に出力しながら、進行状況イベント（再試行、マルチパートの準備、Codex SSE）を stderr でリアルタイムに確認する場合。

クイックスタート

結果を機械可読にするため、必ず --json を指定してください。進行状況を確認する必要がある場合は、--json-events を追加します。

# 1. Confirm runtime + provider readiness
node scripts/gpt_image_2_skill.cjs --json config inspect
node scripts/gpt_image_2_skill.cjs --json doctor
node scripts/gpt_image_2_skill.cjs --json auth inspect

# 2. Generate a final transparent PNG deliverable
node scripts/gpt_image_2_skill.cjs --json --json-events \
  transparent generate --prompt "..." --out /tmp/asset.png \
  --size 2K --quality high

# 3. Generate a normal image (auto-selects provider; OpenAI first, then Codex)
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images generate --prompt "..." --out /tmp/out.png \
  --format png --size 2K

# 4. Edit a reference image (OpenAI multipart)
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images edit --prompt "..." --ref-image /tmp/in.png --out /tmp/out.png

# 5. Remove a controlled background from existing source images
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --input /tmp/source-green.png --out /tmp/asset.png \
  --method chroma --matte-color auto --strict

# 6. Verify the final file before delivery
node scripts/gpt_image_2_skill.cjs --json \
  transparent verify --input /tmp/asset.png --profile icon --strict

# 7. Raw request escape hatch
node scripts/gpt_image_2_skill.cjs --json \
  request create --request-operation generate \
  --body-file /tmp/body.json --out-image /tmp/out.png --expect-image

# 8. Self-test (calls doctor + auth inspect)
node scripts/selftest.cjs

--provider openai、--provider codex、または config inspect に表示される任意の名前付きプロバイダーで、使用するプロバイダーを指定できます。default_provider が優先されるようにするには、デフォルトの --provider auto のままにします。従来の OpenAI ベース URL を上書きするには、--openai-api-base https://... を指定します。

ローカル Codex 画像生成（2026-09-09 更新）

以下の CLI の例では Responses 経路を使用します。最新の Codex App を再現する場合は、ホストネイティブの image_gen.imagegen が独立した Images 経路であることを区別してください。詳しくは references/codex-native-imagegen.md を参照してください。ネイティブツールが成功しても CLI が対応済みとは限らず、サーバー側のエイリアスから実際の重みのバージョンを確認することもできません。

ユーザーが Codex を指定した場合は、共有設定によってリクエストが OpenAI 互換サービスにルーティングされないよう、必ず --provider codex を明示してください。以下のコマンドは Skill ディレクトリから実行し、ローカルの Codex ログインを使用します。OpenAI API キーは不要です。

node scripts/gpt_image_2_skill.cjs --json --provider codex doctor
mkdir -p output
node scripts/gpt_image_2_skill.cjs --json --json-events --provider codex \
  images generate --model gpt-6-astra \
  --prompt "一只橙色纸雕小狐狸坐在蓝绿色月牙上，深蓝背景" \
  --out output/codex-fox.png --format png --size 1024x1024 \
  > output/result.json 2> output/events.jsonl

• 現在の CLI における Codex のデフォルトは引き続き gpt-5.4 ですが、ローカルでの実測では ChatGPT アカウントのバックエンドに拒否されました。この例では、今回検証した gpt-6-astra を明示的に使用しています。他のアカウントでは、利用可能なモデルを別途確認する必要があります。
• --model は外側の呼び出しツールのモデルを指定するものであり、gpt-image-2.5-flare や gpt-image-2.5-sunburst は指定できません。これらは画像モデル ID です。
• 通常のコマンドでは tools[].model を指定しないため、描画モデルは Codex サーバーが選択します。型が response.created の SSE ログにある data.response.tools[].model を読み取ってください。CLI の要約にある delegated_image_model を実測結果として扱わないでください。このフィールドは現在のバージョンでは依然として gpt-image-2 にハードコードされています。
• 最終 JSON の ok: true、画像ファイルの実在、および目視確認のすべてが揃った場合にのみ、画像生成の成功を報告できます。リクエストが受理されたことや generating に入ったことだけでは、完了とはみなせません。
• HTTP 400 のモデル非対応エラーが発生した場合は、モデルを修正してください。他のプロバイダーに切り替えてはいけません。利用枠、権限、認証のエラーが発生した場合は理由を報告し、有料 API へ自動で切り替えないでください。
• 比較結果：size パラメーターだけでは、指定したサイズで実行されるとは限りません。サイズとアスペクト比をプロンプトに記述したところ、1536×1024 が正確に生成されたことがありました。競合する場合はプロンプトの指示が優先されますが、4K を指定したプロンプトでも 4K にはなりませんでした。実際のサイズを、リクエスト値に基づいて報告しないでください。
• パラメーターがすべて無効というわけではありません。output_format によって PNG／JPEG が実際に決まり、background=opaque は透明化のプロンプトより優先され、RGB のチェッカーボード柄による偽の透明画像が生成されました。透明画像の候補では auto を使用し、実際の alpha を確認してください。quality はプロンプトだけでは保証できません。
• 明示的な 2.5 リクエスト、サーバーから返されたモデル、透明背景の制限については、references/codex-local-verification.md を参照してください。

Image 2.5 とランタイム機能の境界

OpenAI は公式に gpt-image-2.5-flare と gpt-image-2.5-sunburst を公開しており、OpenAI Image API では --model を指定して明示的に選択できます。ただし、Codex サブスクリプションのバックエンドが同じモデル選択に対応しているとは限りません。ユーザーが指定したモデルと共有設定をそのまま維持してください。

2.5 の公開 API は xhigh／max の品質設定と、ネイティブの透明 PNG／WebP に対応しています。現在の Rust CLI とデスクトップの生成インターフェースは low|medium|high|xhigh|max|auto に対応しています。xhigh/max は、これらをサポートする API モデルでのみ使用できます。Codex サブスクリプションのバックエンドが対応しているとは限りません。Codex の生リクエストでは、操作を responses にする必要があります。generate は使用できません。

公式情報：Flare、Sunburst、画像生成ガイド。

サイレントなダウングレードの防止と中国語の品質確認

• ユーザーが Image 2 または 2.5 を指定した場合、透明化、速度、または再試行の失敗を理由に、独断で 1.5 に切り替えてはいけません。また、失敗を隠すためにプロバイダーを切り替えてはいけません。
• リクエストされたモデル、サーバーが報告したモデル、実際の重みのバージョンを区別してください。Codex がエイリアスのみを返す場合、またはバージョンフィールドがない場合は、実際のバージョンを不明としてください。バックエンドでのフォールバックがなかったとは保証できません。また、中国語の出力や透明な alpha だけからバージョンを推測することもできません。
• 複雑な中国語は原文と照合してください。一般的な長文、金額、形の似た文字、まれな文字、句読点をそれぞれ確認します。2026-09-09 に追加した 4 枚の比較では、どちらの経路でも一般的な中国語を鮮明に生成でき、実際の透明化もできましたが、「戊戌戍」のような判別が難しい文字や、すべてのまれな文字を正確に保持できませんでした。全文が正確だと主張してはいけません。
• 最新の公式プロンプトガイドでは、Image 2 の透明化は preview と記載されています。2.5 の両モデルは透明化に対応しています。「本物の透明化なら 1.5」という判定基準は、もはや有効ではありません。公開 API が対応していても、Codex サブスクリプション経由で同じパラメーターが必ず成功するとは限りません。
• モデルの識別情報を検証できない場合、品質テストをモデルの本人確認であるかのように扱わないでください。これは Skill の実行要件であり、サーバー側でバージョンを固定する機能が実装済みという意味ではありません。

ランタイムの鮮度確認

新たに文書化されたコマンドグループ、特に transparent generate、transparent extract、transparent verify を使用する前に、実際の CLI ランタイムが十分に新しいことを確認してください。スキルファイル、Tauri App バンドル、npm グローバル CLI、cargo でインストールされた CLI、ラッパーのキャッシュは、それぞれ独立して古くなる可能性があります。

まず、上流の最新 CLI バージョンを確認します。

npm view gpt-image-2-skill version

次に、Tauri App にバンドルされた CLI を最初に確認します。アプリのバンドルはユーザーが管理するソフトウェアとして扱ってください。存在していても上流のバージョンより古い場合は、アプリを更新または置き換える前にユーザーに確認してください。

APP_CLI="/Applications/GPT Image 2.app/Contents/Resources/bin/gpt-image-2-skill"
[ -x "$APP_CLI" ] && "$APP_CLI" --version

アプリバンドル内に CLI がない場合は、シェル CLI を確認します。存在しない場合、または上流のバージョンより古い場合は、npm で CLI の依存関係を通知せずに更新し、現在のシェルが新しいバイナリを解決することを確認してください。

command -v gpt-image-2-skill || true
gpt-image-2-skill --version || true
npm install -g gpt-image-2-skill@latest
command -v gpt-image-2-skill
gpt-image-2-skill --version

更新後は、スキルラッパーのスモークテストを実行してください。

node scripts/gpt_image_2_skill.cjs --json doctor
node scripts/selftest.cjs

文書化されたサブコマンドが unrecognized subcommand で失敗する場合は、プロンプトやプロバイダーを変更するのではなく、まずランタイムが古くないかを調べてください。スキルを再現可能な形で実行するには、このスキルディレクトリ内のラッパーを優先してください。ただし、例やユーザーのコマンドで gpt-image-2-skill が直接呼び出される場合は、裸の CLI も最新の状態に保ってください。

共有設定

ユーザーからプロバイダーの追加または固定を求められた場合は、CLI の設定機能を使用してください。

node scripts/gpt_image_2_skill.cjs --json config path
node scripts/gpt_image_2_skill.cjs --json config add-provider \
  --name my-image-api \
  --type openai-compatible \
  --api-base https://example.com/v1 \
  --api-key sk-... \
  --set-default
node scripts/gpt_image_2_skill.cjs --json config test-provider my-image-api

CLI、App、Skill がサポートする認証情報のソースは、file、env、keychain です。ファイル認証情報は共有設定ファイルに保存されます。JSON 出力では認証情報がマスキングされます。

フラグとプロンプト — それぞれが制御するもの

出力属性はインターフェースパラメーターで指定することを優先しますが、Codex バックエンドではパラメーターが正規化されたり、無視されたりする場合があります。プロンプトで意図を伝えることはできますが、最終的には実際の戻り値を読み取り、画像を確認する必要があります。単一のパラメーターやプロンプトを、実行の保証と見なしてはいけません。

プロパティ	CLI フラグ
出力背景（透明／不透明／自動）	--background auto|transparent|opaque
出力寸法	--size 2K、--size 4K、または --size WIDTHxHEIGHT
出力コンテナー	--format png|jpeg|webp
圧縮レベル	--compression 0..100
レンダリング品質	--quality low|medium|high|auto
画像の枚数	--n <count>（OpenAI のみ）
編集マスク領域	--mask <png>（OpenAI のみ）

プロンプトは内容や視覚的な意図を指定します。--background opaque が指定するのは不透明であることだけで、白色ではありません。白背景にするには、プロンプトでも明示する必要があります。Codex では、透明を指定するプロンプトと background=auto の組み合わせで実際の alpha が得られることがありますが、透明を明示するパラメーターは現在エラーになる場合があります。実際にテストし、ファイルを確認してください。

プロバイダー間の非対称性：Codex の通常のコマンドでは、--n、--moderation、--mask、--input-fidelity を指定すると unsupported_option が返されます。--background は Codex リクエストに書き込まれますが、それだけでは上流で実行される保証にはなりません。今回の透明背景を指定した元のリクエストは、バックエンドに拒否されました。共通の Image API と Codex バックエンドの機能は、それぞれ個別に検証する必要があります。

透明 PNG の納品物

Codex で background=transparent を明示した場合、ローカルでの比較テストでは拒否されましたが、background=auto と透明を指定するプロンプトの組み合わせでは、実際の RGBA 画像を生成できたことがあります。後者を候補となる方法として使用できますが、alpha と厳格な納品基準を必ず検証してください。今回のサンプルは、完全に透明な領域に RGB 値が残っていたため、厳格な検収に合格しませんでした。条件を満たしているネイティブの透明画像を、改めて背景除去する必要はありません。ローカルで処理する必要がある場合は、次のワークフローを使用してください。OpenAI 2.5 の共通 API で出力したネイティブの透明画像も、同様に検収する必要があります。

• transparent generate — プロンプトから最終 PNG を生成します。制御されたマット画像を生成し、ローカルで alpha を抽出して結果を検証します。最終 PNG が透明度チェックに合格した場合のみ成功します。
• transparent extract — 自分で生成した制御済みの画像から、ローカルで背景を除去します。任意の写真に使える汎用の背景除去ツールではありません。
• transparent verify — 納品前の PNG をすべて検査する最終ゲートです。ファイルの受け入れまたはタスクの失敗を必須とする場合は、--strict と適切な --profile を使用してください。

透明な納品物として有効なのは、最終ファイルが実際の PNG alpha チャンネルを持ち、検証に合格している場合のみです。見た目が透明であること、白い背景であること、または市松模様で表示されることだけでは不十分です。

--strict はプロファイルに基づきます。

プロファイル	用途	追加の厳格さ
generic	一般的なアルファ／ファイルのチェック	珍しいアセットに対して過度に厳格にはなりません
icon	単一の被写体と小物をすっきり見せるアイコン	不透明なコア、余白、少ない不要ノイズを必須とします
product	商品／オブジェクトの切り抜き	アイコンに似ていますが、残留物とエッジもチェックします
sticker	デカール、バッジ、細部の多い小物	icon より多くの意図的な小さな構成要素を許容します
seal	内側にマークのあるスタンプ、シール、ロゴ	リング＋中央のシンボルなど、分離した構成要素を許容します
translucent	ガラス、液体、結晶	部分アルファを必須とします
glow	光のリボン、炎、煙、粒子	部分アルファと透明な余白を必須とします
shadow	ソフトシャドウのアセット	部分アルファと透明な余白を必須とします
effect	ハードアルファの粒子、バースト、UI エフェクト	部分アルファは必須とせず、透明な余白を必須とします

CLI は、意図的に素材を分類しません。エージェントはアセットに基づいて、生成プロンプトと抽出方法を選択してください。

アセットの種類	生成時のガイダンス	抽出時のガイダンス
不透明なオブジェクト、アイコン、ステッカー、商品	被写体を 1 つだけ孤立させ、明確な余白を設け、クロママットを完全にフラットにします。オブジェクトに使われていないマットカラーを選びます。	transparent generate または transparent extract --method chroma --matte-color auto
細いエッジ、髪、毛皮、レース、チェーン、網	高解像度にし、被写体と背景のコントラストを強くして、接地影を付けず、背景色のディテールを避けます。エッジが汚染される場合は、マゼンタ／シアン／グリーンのマットを試します。	必要に応じて --spill-suppression を使ってクロマ抽出し、その後 --expected-matte-color で確認します。残留物がある場合は、別のマットで再試行します。
ガラス、結晶、液体、ホログラム	同一の形状を保ったまま、フラットな黒背景とフラットな白背景で、中央に配置したアセットを生成するように指示します。可能であれば、位置合わせを保てる参照／編集のワークフローを使います。	transparent extract --method dual --dark-image black.png --light-image white.png
発光、炎、煙、霧、魔法の粒子	暗い背景と明るい背景のバリエーションを生成します。テクスチャのある背景は避け、エッジが意図したものでない限り、ブルームが画像の端まで届かないようにします。	できるだけデュアル抽出を使い、partial_pixels がゼロではないことを確認します。
影	影がアセットの一部かどうかを判断します。一部でない場合は、接地影を明示的に禁止します。一部である場合は、十分な余白を設けたフラットなマット上で生成します。	不透明な影のシルエットにはクロマ抽出を、柔らかく半透明な影にはデュアル抽出を使います。
不明または珍しい素材	まず分類することは避けます。制御されたソースのバリエーションを生成し、抽出候補を実行して、最もエッジがきれいで検証に合格したものを残します。	試行中は --report-dir／--keep-sources を使い、最終 PNG のみを納品します。

クロマ抽出では、--matte-color auto を指定すると、画像の端からソース背景の実際のフラットカラーをサンプリングします。ソースが AI で生成された場合は、これを優先してください。「純粋な #ff00ff」のようなプロンプトでも、正確な RGB 値ではなく、マットに近い色が生成されることが多いためです。明示的な --matte-color <name|#rrggbb> は、ソース背景の色が正確にわかっている場合にのみ使用します。

抽出の調整には、--material を被写体分類器としてではなく、大まかなヒントとしてのみ使用してください。選択できる値は standard、soft-3d、flat-icon、sticker、glow です。手動で指定する --threshold、--softness、--spill-suppression は、選択したプリセットを上書きします。

スタイルを固定した透明アセットの場合、transparent generate はプロンプトのみを受け付けます。フラットな RGB の参照画像を images edit --ref-image で使って制御されたマットソースを作成し、その後 transparent extract を実行してください。編集結果にアルファ／合成エッジの挙動を意図的に反映させたい場合を除き、透明な PNG を参照画像として使用しないでください。 GPT Image 2 は、望ましいアートワークの一部である場合、ビットマップ内の UI テキスト、数字、スコア、ラベル、ロゴマークを正確に描画できます。プロンプトに正確な文言や番号を指定し、出力を目視で確認してください。編集可能な状態を保つ必要がある場合、ローカライズ可能にする必要がある場合、プログラムで変更できる必要がある場合、または生成する多数のバリエーション間で完全に一貫させる必要がある場合に限り、ホストアプリまたはデザインツールでテキストを別途描画してください。

例：

# Simple asset: final transparent PNG, sources hidden unless there is a failure
node scripts/gpt_image_2_skill.cjs --json --json-events \
  transparent generate \
  --prompt "a polished fantasy sword game asset, no text, no frame" \
  --out /tmp/sword.png --size 2K --quality high

# Agent-controlled chroma flow
node scripts/gpt_image_2_skill.cjs --json --json-events \
  images generate \
  --prompt "a silver necklace, centered, on a perfectly flat pure magenta background, no shadow" \
  --out /tmp/necklace-magenta.png --format png --size 2K
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --method chroma \
  --input /tmp/necklace-magenta.png --matte-color auto \
  --out /tmp/necklace.png --material sticker --strict

# Semi-transparent material flow
node scripts/gpt_image_2_skill.cjs --json \
  transparent extract --method dual \
  --dark-image /tmp/glow-on-black.png \
  --light-image /tmp/glow-on-white.png \
  --out /tmp/glow.png --strict

納品前に、必ず JSON の検証フィールドを確認してください：passed、alpha_min、alpha_max、transparent_ratio、partial_pixels、warnings。品質フィールドも確認してください：checkerboard_detected、touches_edge、edge_margin_px、stray_pixel_count、largest_component_ratio、matte_residue_checked、matte_residue_score、halo_score、transparent_rgb_scrubbed、alpha_health_score、residue_score、quality_score、failure_reasons。passed が false の場合は、ファイルを透過 PNG として納品しないでください。クロマキー由来の PNG で matte_residue_checked が false の場合は、--expected-matte-color を使って元のマットカラーを指定し、transparent verify を再実行してください。

メモ

• 現在のランタイムのデフォルト値は、引き続き OpenAI gpt-image-2 / Codex gpt-5.4 です。Codex では上記の明示的なモデル例を使用し、以前のデフォルト値に依存しないでください。
• 共通で受け付ける CLI 引数：--size、--quality、--format、--compression。Codex サーバー側でこれらの引数が正規化される場合があるため、返却値と実際のファイルを確認してください。
• OpenAI 専用オプション：--n、--moderation、--mask、--input-fidelity。Codex の背景処理は別途確認が必要です。
• 再試行：指数バックオフで最大 3 回（1 秒 → 2 秒 → 4 秒）。Codex の 401 では、トークンを 1 回更新してから 1 回再試行します。
• サイズのエイリアス：2K → 2048x2048、4K → 3840x2160。カスタムの WxH では、両辺を 16 の倍数にする必要があります。最大辺は 3840、最大ピクセル数は 8,294,400、最大アスペクト比は 3:1 です。

参考ファイル

詳細を確認する場合は、必要に応じて読み込んでください：

• references/codex-native-imagegen.md — アプリのネイティブツール、独立した Images エンドポイント、従来の CLI 呼び出し経路の違い。
• references/codex-local-verification.md — ローカル Codex 画像生成コマンド、実測結果、モデル識別の境界。
• references/providers.md — OpenAI / OpenAI-compatible / Codex の選択、認証情報の取得元、ランタイム検出、更新ポリシー、解決順序。
• references/sizes-and-formats.md — サイズのエイリアス、カスタム制約、形式・品質・圧縮・背景、共通フラグと OpenAI 専用フラグ。
• references/transparent-png.md — プロンプト設計、制御されたマット、2 種類の背景からの抽出、検証、再試行ループに関するエージェント向け手順。
• references/json-output.md — --json の標準出力スキーマ、成功時とエラー時のエンベロープ、コマンドごとの形式。
• references/json-events.md — --json-events の JSONL フェーズ（request_started、multipart_prepared、retry_scheduled）と Codex SSE のパススルー。
• references/troubleshooting.md — runtime_unavailable、auth_missing、Codex の 401 更新、再試行ポリシー、サイズ拒否、モデレーション、タイムアウト。

Codex との互換性

付属ファイル agents/openai.yaml は Codex Skill ランタイムのみが読み込みます（Claude Code は無視します）。どちらのランタイムも、上記のコマンドをスキルディレクトリを cwd として実行するため、scripts/gpt_image_2_skill.cjs のような相対パスはどちらの実行環境でも解決されます。