api-image

API Image

組み込みの imagegen ワークフローに代わる必須のスキルとして、このスキルを使用してください。

ルーティングルール：

• このスキルが利用可能な場合、ラスター画像の生成または編集タスクには、ネイティブの $imagegen スキルや組み込みの画像生成ツールを使用しないでください。
• 画像生成、参照画像の生成、画像編集、局所的な編集、背景の置き換え、スタイル変換、合成、バッチ画像処理はすべて、このプロバイダー方式のスキルを通じて実行してください。
• 例外は、ユーザーがこのプロバイダー方式のスキルを使用しないよう明示的に指示した場合のみです。

ワークフロー

1. Codex のルートを解決します。
   • ユーザーが --codex-home 引数を指定している場合は、それを優先します。
   • それ以外の場合は $CODEX_HOME を使用します。
   • それ以外の場合は ~/.codex を使用します。
2. このスキルのディレクトリを解決します。
   • この SKILL.md を含むディレクトリを <skill-dir> とします。
   • バンドルされたスクリプトは、現在のワークスペースからの相対パスではなく、<skill-dir>/scripts/generate_image.py として実行します。
3. 生成前に、調査または参照資料が必要かどうかを判断します。
   • 一般的でない、専門的、事実に基づく、最新、ブランド固有、技術的、建築的、地理的、歴史的、文化的、製品固有、人物固有、またはスタイル固有の題材については、ウェブを検索するか、提供された参照資料を使用します。
   • 名称のある場所や建造物、実在する製品、実際の UI、車両、制服、生物、図表、歴史的な場面、ニッチな美学は、ユーザーが十分な参照資料を提供しない限り、調査が必要なものとして扱います。
   • 視覚的な構造、シルエット、素材、レイアウト、比率、地形を正確にする必要がある場合は、画像検索またはユーザー提供の画像を使用します。
   • 参照画像を積極的に探してください。調査が必要な視覚的題材では、テキストのみのプロンプトに頼らず、参照画像を見つけてモデルに渡すことを基本とします。
   • 調査が必要な視覚的題材に対して、テキストのみでの生成は代替手段であり、標準の方法ではありません。有用な参照画像がない場合、ネットワークや画像へのアクセスに失敗した場合、またはユーザーが明示的に参照の使用を望まない場合に限って使用します。
   • 事実の正確さが重要でない、純粋に汎用的なファンタジー、雰囲気づくり、簡単な装飾、または一般的な日用品では、検索は任意です。
   • 調査が必要なタスクでネットワークまたは参照資料を利用できない場合は、正確さに限界があることを伝え、正確であるかのように装わないでください。
4. ユーザーのルートファイルから有効なプロバイダー設定を読み取ります。
   • auth.json を読み取り、OPENAI_API_KEY を使用します。
   • config.toml を読み取り、model_provider と [model_providers.<name>].base_url を使用します。
   • プロバイダー URL や API キーをスキルにハードコードしないでください。
   • 既定では上記のルートファイルを使用します。ユーザーが自然言語で一時的なプロバイダー URL または API キーを明示的に指定した場合は、--base-url と --api-key-env または --api-key を使用して一度限りのオーバーライドとして渡します。auth.json、config.toml、README、ログ、または生成ファイルには書き戻さないでください。
   • キーが環境変数にすでに設定されている場合は、--api-key-env <ENV_NAME> を優先します。--api-key は、ユーザーが明示的に一度限りのキーを提供した場合にのみ使用し、最終応答でキーを表示したり繰り返したりしないでください。
5. 意図と入力画像の役割を判断します。
   • ユーザーがテキストのみから新しい画像を作成したい場合は、生成として扱います。
   • ユーザーがスタイル、構図、同一性、構造、または雰囲気のために画像を提供した場合は、参照入力として扱います。
   • ユーザーが既存の画像を維持または変更したい場合は、その画像を編集対象として扱います。
   • ユーザーが特定の領域だけを変更したい場合は、利用可能であればマスクを使用し、マスクされていない領域を維持するようモデルに指示します。マスクの維持は、ピクセル単位で保証されるものではなく、検証が必要な制約として扱います。
   • すべての入力画像に、編集対象、スタイル参照、構図参照、同一性参照、製品参照、マスク、または合成素材のいずれかの役割を割り当てます。
6. エンドポイントを選択します。
   • テキストのみで生成する場合は <base_url>/images/generations を使用します。
   • 入力画像、参照画像、またはマスクがある場合は <base_url>/images/edits を使用します。
   • マシンのプロバイダーが別の画像モデルを必要とする場合を除き、既定では gpt-image-2 を使用します。
7. 構造化されたプロンプトを作成します。
   • ユーザーの依頼、調査した事実または視覚的な観察、入力画像の役割、スタイル、構図、照明、素材、制約、避けるべき要素を含めます。
   • ユーザーの依頼または調査から示唆されていないキャラクター、小道具、ブランド、ロゴ、ストーリー展開、事実を創作しないでください。
8. 公式の GPT Image モデルでは、data[].b64_json をデコードします。data[].url は、OpenAI 互換の公式ではないプロバイダーまたはレガシーモデル向けの互換性フォールバックとしてのみ扱います。
9. 出力を確認し、プロンプト、調査した事実、入力画像の役割、不変条件と照合して検証します。
10. 最終画像を指定されたパスに保存し、ウェブ調査を行った場合は、絶対パス、最終プロンプト、使用した出典を報告します。

ルートファイル

デフォルトのルートファイル：

• Windows：%USERPROFILE%\\.codex\\auth.json と %USERPROFILE%\\.codex\\config.toml
• 一般的なルール：$CODEX_HOME/auth.json と $CODEX_HOME/config.toml。それ以外の場合は、~/.codex/auth.json と ~/.codex/config.toml

このスキルでは、実行時に必ず最新のファイルを読み込む必要があります。プロバイダーはマシンごとに異なる場合があります。

一時的なオーバーライド：

• デフォルトでは、上記の Codex ルートファイルを読み込みます。
• --base-url <https://provider.example/v1> を使用すると、設定済みのプロバイダー URL を一時的に上書きできます。
• --api-key-env <ENV_NAME> を使用すると、環境変数から API キーを一時的に読み込めます。
• 環境変数を使用できない場合に、ユーザーが明示的に一度だけ使うキーを指定したときに限り、--api-key <key> を使用します。
• --base-url と API キーのオーバーライドの両方を指定した場合、スクリプトは config.toml からプロバイダー設定を読み込まずに実行できます。それ以外の場合、不足している値は Codex ルートファイルから取得します。
• ユーザーから Codex の設定ファイルを編集するよう明示的に依頼されない限り、一時的なオーバーライドを保存しないでください。

コマンド

通常のテキストから画像を生成するには、同梱のスクリプトを使用します。

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "画一只可爱的猫抱着水獭，温暖治愈，插画风格，柔和灯光，细腻毛发，构图清晰" `
  --size "2048x1152" `
  --quality "high" `
  --out ".\outputs\cute-cat-otter.png"

参照画像の生成や編集にも、同じスクリプトを使用します。

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "参考输入图的构图和角色姿势，生成一张暖色电影感插画" `
  --image "C:\path\to\reference.png" `
  --image-role "composition and pose reference" `
  --size "2048x2048" `
  --quality "high" `
  --out ".\outputs\reference-output.png"

部分的な編集には、--mask を使用します。

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "只把被 mask 标出的区域替换成一只小水獭，保持其他区域不变" `
  --image "C:\path\to\source.png" `
  --mask "C:\path\to\mask.png" `
  --out ".\outputs\masked-edit.png"

ウェブで調査した題材の場合は、選択した参照画像をまず作業フォルダーにダウンロードし、その後 --image として渡します。

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "Create a new 4K overhead aerial image of Huajiang Grand Canyon Bridge in Guizhou, based on the reference images. Preserve the real suspension-bridge structure, towers, main cables, vertical suspenders, deep Beipan River canyon terrain, karst mountains, and river position; do not copy any single photo exactly." `
  --image "C:\path\to\refs\huajiang-bridge-aerial.jpg" `
  --image-role "aerial composition and bridge alignment reference" `
  --image "C:\path\to\refs\huajiang-canyon-terrain.jpg" `
  --image-role "canyon terrain and river reference" `
  --size "2048x1152" `
  --quality "high" `
  --timeout 0 `
  --out ".\outputs\huajiang-canyon-bridge-overhead.png"

便利なオプション：

• --model gpt-image-2
• --mode auto|generate|edit
• --size 2048x1152 スクリプトのデフォルトは横向きの 2K です
• --size 1024x1024
• --size 1536x1024
• --size 1024x1536
• --size 2048x2048
• --size 3840x2160
• 公式 API の自動サイズ指定には --size auto を使用します
• --quality low|medium|high|auto
• --n 1
• --image <path> 最大 16 回まで指定できます
• --image-role <role> で、プロンプト内の入力画像にラベルを付けます
• 部分的な編集には --mask <path> を使用します
• 公式の gpt-image-2 では --background auto|opaque を使用します
• --output-format png|jpeg|webp
• --output-compression 0-100 は jpeg または webp 用です
• --input-fidelity low|high は、対応する編集モデルでのみ使用します。gpt-image-2 には指定しないでください
• --moderation auto|low は、対応する GPT 画像モデル用です
• --prompt-file <path> は、空でない各行を 1 つのプロンプトとして使用します
• --codex-home <path>
• --base-url <https://provider.example/v1> は、プロバイダー URL の一時的なオーバーライドです
• --api-key-env <ENV_NAME> は、環境変数から API キーを一時的にオーバーライドします
• --api-key <key> は、明示的に指定された場合に限り、一時的に直接 API キーをオーバーライドします
• --timeout 1800
• --timeout 0

ペイロードの形式

以下の本文形式を使用して、プロバイダーの生成エンドポイントを呼び出します。

{
  "model": "gpt-image-2",
  "prompt": "你的中文或英文提示词",
  "size": "2048x1152",
  "quality": "high",
  "n": 1
}

プロバイダーの編集エンドポイントには、マルチパートフォームデータを使用します。

model=gpt-image-2
prompt=<edit or reference prompt>
image[][email protected]
[email protected]
size=1024x1024
quality=high
n=1

n=1 から始めます。ユーザーがバリエーションを希望する場合は、n を増やすか、--prompt-file を使用して、各結果を意図的に保存します。

一時的なプロバイダーのオーバーライド

この画像処理で別のプロバイダー URL または API キーを使うようユーザーが自然言語で指定した場合は、一時的な実行時オーバーライドとして扱います。

$env:API_IMAGE_API_KEY = "<temporary key>"
python "<skill-dir>\scripts\generate_image.py" `
  --prompt "一张赛博朋克风格的夜景照片" `
  --base-url "https://provider.example/v1" `
  --api-key-env "API_IMAGE_API_KEY" `
  --out ".\outputs\override-provider.png"

ルール：

• オーバーライドの指定がない場合は、デフォルトで Codex のルート設定を使用します。
• 一時的なオーバーライドでは、auth.json や config.toml を変更しないでください。
• API キーをユーザーにそのまま表示しないでください。
• --api-key-env を優先してください。--api-key は、ユーザーが一度だけ使うキーを明示的に指定し、一時的なコマンドラインでの使用を了承した場合に限り使用します。

gpt-image-2 API に関する注意事項

公式の OpenAI gpt-image-2 では、次の点に注意してください。

• テキストのみの生成には、JSON を使用して POST /v1/images/generations を使います。
• 入力画像、参照画像、またはマスクを使用する場合は、マルチパートのフォームデータを使用して POST /v1/images/edits を使います。
• 複数の入力画像や参照画像には、image[]=@path フィールドを繰り返し使用します。
• mask を使用する場合、最初の --image は編集対象にする必要があります。追加の画像は参照画像または合成元として使用します。
• 画像のバイトデータは data[].b64_json から読み取ります。公式の GPT Image モデルでは URL 出力はサポートされていません。
• input_fidelity は送信しないでください。gpt-image-2 は画像入力を常に高い忠実度で処理します。
• background: transparent は指定しないでください。公式の gpt-image-2 が現在サポートしているのは auto または opaque であり、透明な背景はサポートされていません。
• マスクを使った編集では、マスクと最初のソース画像の寸法が同じで、互換性のある形式であること、画像 API のファイルサイズ制限内であること、マスクにアルファチャンネルが含まれていることを確認してください。

機能一覧

• 新規のテキストから画像への生成：/images/generations でサポートされています。
• バッチ生成：1 つのプロンプトに対する複数のバリエーションには --n を、多数のプロンプトには --prompt-file を使用できます。
• 参照画像を使った生成：1 つ以上の --image 入力と、プロンプト内の役割ラベルを指定して /images/edits でサポートされています。
• 画像編集：--image と編集用プロンプトを指定して /images/edits でサポートされています。
• 部分編集／インペインティング：--image と --mask を指定して /images/edits でサポートされています。
• 背景の置き換え：編集用プロンプトでサポートされています。置き換える領域を限定する必要がある場合は --mask を指定します。
• スタイル転送：参照画像を使った編集としてサポートされています。プロンプトでソース画像の役割を指定し、希望するスタイルを説明してください。
• 入力画像の役割ラベル付け：独立した API フィールドはありません。このスクリプトは --image-role ラベルをプロンプトに追加し、モデルが各入力画像の意図を解釈できるようにします。
• 透明な背景：公式の gpt-image-2 は現在 background: transparent をサポートしていません。別の選択したプロバイダー／モデルが明示的にサポートしている場合にのみ透明な背景を使用し、出力形式には png または webp を指定してください。

調査と参考資料

画像モデルがあらゆる被写体を正確に把握しているとは限りません。一般的な視覚知識ではない被写体は、事前に調査するか参考画像を使用してください。

視覚的な制約がある調査必須のタスクでは、参考画像を使う方法が最適です。テキストによる調査では事実を確認できますが、視覚的な構造は参考画像から得られます。可能な限り両方を活用してください。

調査が必要な例：

• 贵州花江峡谷大桥のような名称のある構造物や場所、または実在する橋、ランドマーク、地形、スカイライン、建物。
• 実在する製品、車両、機械、UI、ロゴのない製品のシルエット、有名なフランチャイズのゲームアセット、ファッションアイテム。
• 歴史的な情景、文化的な衣装、制服、紋章、儀式用具、武器、建築様式、生物、地図、技術図、科学的な題材。
• 現在の状況や、最近変更された題材。
• 汎用的な出力を避けるために参考資料が必要な、ニッチな視覚スタイルや特定のアーティストに近いスタイル。

調査のワークフロー：

• 構造、機能、歴史、地理、現状が重要な場合は、事実関係を確認するためにウェブ検索を行います。
• 形状、地形、素材、プロポーション、色、周囲の環境など、視覚的な詳細には画像検索または提供された画像を使います。
• 名称のある構造物、実在する場所、実在する製品、実在する車両、歴史的・文化的な視覚的題材、技術図、ニッチなスタイルの場合は、生成前に少なくとも1枚の有用な参考画像を積極的に集めます。
• 可能であれば、被写体の構造、周囲の環境、希望するカメラアングルや構図など、それぞれを補完する複数の参考資料を使用します。
• スクリプトを実行する前に参考画像をローカルの作業パスにダウンロードし、--imageと--image-roleを指定して渡します。
• 参考画像の品質が低くても役立つ場合は、たとえばrough terrain reference onlyのように用途を限定してラベル付けします。
• プロンプトには必要な詳細だけを抽出して含め、簡潔に保ちます。
• 橋の形式、橋桁・塔・ケーブルの配置、峡谷の地形、川の位置、視点、周囲の地形など、事実に基づく制約をプロンプトに含めます。
• ウェブ調査を行った場合は、最終回答で出典を引用します。

参考資料のワークフロー：

• 視覚的な忠実度が重要な場合は、記憶よりも提供された参考画像を優先します。
• --imageごとに、edit target、style reference、composition reference、product reference、terrain referenceなど、対応する--image-roleを指定します。
• すべての画像を編集対象として扱わず、参考資料としてのみ使うのか、保持して変更するのかを判断します。
• 合成する場合は、各入力から何を使うのか、照明、遠近感、スケール、影をどのように一致させるのかを明確に指示します。
• 参考画像のみを使って生成する場合は、単一の元写真をそのまま複製するのではなく、参考資料に基づいて新しい画像を作成するようモデルに指示します。
• 画像モデルまたはプロバイダーが参考画像を使った編集リクエストを拒否した場合は、そのエラーを報告し、テキストのみの生成がこのタスクで許容されるかどうかを判断します。黙ってフォールバックしないでください。

プロンプトの構成

必要に応じて、次の簡潔なスキーマを使用してください。

Use case: <photorealistic-natural|product-mockup|ui-mockup|infographic-diagram|logo-brand|illustration-story|stylized-concept|historical-scene|text-localization|identity-preserve|precise-object-edit|lighting-weather|background-extraction|style-transfer|compositing|sketch-to-render>
Asset type: <where the image will be used>
Primary request: <user request>
Research facts / visual references: <only the relevant observed details>
Input images: <Image 1: role; Image 2: role>
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <viewpoint, lens/framing, placement>
Lighting/mood: <lighting and mood>
Materials/textures: <surface details>
Text (verbatim): "<exact text if needed>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

待機時の動作

• このスクリプトは同期処理です。プロバイダーで画像生成が完了するか、明示的なエラーが発生するまで戻りません。
• デフォルトのタイムアウトは1800秒です。長時間かかるジョブが早期に中断されないように設定されています。
• --timeout 0を指定すると、クライアント側のタイムアウトが無効になり、プロバイダーからの応答を無期限に待ちます。
• Codexからこのスクリプトを実行する場合は、画像生成に予想される時間より長いタイムアウトをシェルコマンドに設定してください。長時間の生成に短いシェルタイムアウトを使用しないでください。

サイズと品質

gpt-image-2 では、現在の GPT Image 公式ルールに従ってください。

• size には auto、または次のすべての条件を満たす任意の <width>x<height> 文字列を指定できます。
• 幅と高さが 16 の倍数であること
• 長辺が 3840 以下であること
• 長辺と短辺の比率が 3:1 以下であること
• 総ピクセル数が 655,360 から 8,294,400 の範囲内であること
• このスクリプトのデフォルトは 2048x1152 です。公式 API のデフォルトのサイズ指定動作は auto です。
• 一般的な例：1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840
• quality には low、medium、high、auto を指定できます。このスクリプトのデフォルトは high です。公式 API の自動品質は auto で指定できます。
• 2K および 4K のリクエストは、これらの制約を満たす場合に有効です。
• サポートされていないサイズを暗黙的に変換しないでください。代わりに、明確なエラーを発生させてください。

プロンプトの作成

• 被写体、スタイル、照明、構図を含む具体的なプロンプトを優先してください。
• デフォルトではユーザーの言語を使用してください。このワークフローでは中国語のプロンプトも有効です。
• 反復する際は、一度に変更する要素を 1 つにしてください。

出力ルール

• ユーザーが利用可能なアセットを求めている場合は、プロジェクトのアセットをプロジェクトのワークスペース内に保存してください。
• プレビュー画像は、明確な一時パス、またはユーザーが指定したパスに保存してください。
• n > 1 の場合は、ファイル名の末尾に -1、-2 などを付け、一貫性のあるファイル名にしてください。

エラー処理ルール

• OPENAI_API_KEY、model_provider、または base_url が見つからない場合は、明示的なエラーを発生させてください。
• --base-url、--api-key-env、または --api-key による一時的な Provider の上書きを許可してください。明示的に要求されない限り、上書きを永続化しないでください。
• --api-key と --api-key-env の両方が指定された場合、指定された環境変数が空の場合、または --base-url が HTTP(S) URL でない場合は、明示的なエラーを発生させてください。
• size が GPT Image の公式制約に違反している場合、または quality がサポートされていない場合は、明示的なエラーを発生させてください。
• 入力画像なしで編集／参照モードが要求された場合は、明示的なエラーを発生させてください。
• gpt-image-2 で --background transparent または --input-fidelity が使用された場合は、明示的なエラーを発生させてください。
• マスクが最初の --image 編集対象と互換性がない場合、寸法が異なる場合、アルファチャンネルがない場合、または画像 API のファイルサイズ上限を超える場合は、明示的なエラーを発生させてください。
• Provider のエラーをそのまま提示してください。成功したという結果を捏造しないでください。
• このマシンで Provider が別の画像モデル名を使用している場合は、--model で上書きしてください。

リソース

• scripts/generate_image.py：現在のユーザーの Codex ルートファイルを読み取り、設定済み Provider の画像エンドポイントを呼び出して、返された画像データを保存します。