gpt-image

gpt-image

GPT Image 2 / 2.5 の生成・編集用エージェント実行手順書です。プロンプトライブラリとパッケージ済み CLI を使用してください。画像 API コードを再実装しないでください。

運用手順

1. リクエストを分類してモデルを決定する：generate、edit、inpaint、multi-reference のいずれかを特定し、アセットの種類、正確なテキスト、アスペクト比、参照画像、安全上の制約、予算／品質を確認します。API を呼び出す前に、以下のモデル選択ルールを適用してください。
2. 参照画像の手順を選ぶ：Image 2 では、以下のギャラリーを優先するワークフローを維持します。2.5 では、明確なブリーフに参照画像の読み込みは不要です。それ以外の場合は、短いタスク範囲を 1 つ選んでください。
3. 必要な場合のみ調整する：ブリーフの内容を維持してください。具体的な不足を補う場合に限り、特定のギャラリー項目、クラフトセクション、またはテンプレートを追加してください。2.5 では、これらを一括で読み込まないでください。
4. 有用な場合は相談する：コストが高い場合、曖昧な場合、または高い仕上がりが求められる場合は、呼び出し前に適合する方向性を 1～3 件と予定サイズ／品質を提示してください。一度に尋ねる質問は簡潔なものを 1 つまでにしてください。モデルが確定している明確な「今すぐ生成」リクエストでは、長い相談を省略してください。
5. 副作用のない事前確認を行う：既存の CLI／スキルがあれば使用してください。コマンドの利用可否（command -v gpt-image）、ツールマネージャーがある場合はインストール済みツールの一覧、または利用可能な場合はランタイム独自のスキルレジストリを確認します。クラウド／ホスト型ランタイムで、ローカルのホームディレクトリパスを前提にしないでください。
6. 無断でセットアップしない：ユーザーがセットアップを明示的に依頼しない限り、再インストール、スキルフォルダーの上書き、.env の作成／変更、API キーの書き込みを行わないでください。グローバル／共有インストールは、明示的な許可がある場合に限ります。
7. CLI のみで実行する：gpt-image または scripts/generate.py を明示的な --model とともに呼び出してください。通常の画像リクエスト用に、新しい generate.py、SDK ラッパー、または場当たり的なスクリプトを作成しないでください。
8. 結果を報告する：出力ファイルのパス、主要なフラグ、および有用な場合は簡潔な改善案を 1 つ提示してください。

最短手順：2.5 モデルが確定済みで、プロンプトが明確な「今すぐ生成」の場合は、必須の参照画像／クラフト確認を省略して事前確認と CLI に進みます。正確で有効なモデルを再確認しないでください。

モデルの選択とプロンプトの調整

選択肢	API モデル ID	推奨用途
Flare	gpt-image-2.5-flare	高速な汎用生成と下書き
Sunburst	gpt-image-2.5-sunburst	正確な参照画像編集と詳細な制御
Image 2	gpt-image-2	既存の Image 2 ワークフローと互換性

• モデルが指定されていない、曖昧（「GPT 2.5」など）、または誤記されている場合は、トレードオフとともに Flare、Sunburst、Image 2 を提示して、明確な質問を 1 つ行い、返答を待ってください。誤記の場合は、黙って訂正せず、意図されている可能性が高い選択肢を提案してください。gpt-image-2.5 を API モデル ID として扱わないでください。
• 正確にサポートされているモデル ID、このメニューからの曖昧さのない選択肢、または今回のタスクについてユーザーがすでに確定した選択肢を使用し、再度尋ねないでください。ユーザーが明示的に「選んで」と言った場合は、選択理由を簡潔に説明して進めてください。常に最も高価な設定を選ぶのではなく、タスクと予算を考慮してください。
• 選択した ID は必ず --model に渡してください。CLI の後方互換性を保つデフォルトは gpt-image-2 ですが、このデフォルトを、エージェントがユーザーの選択を決定する代わりにしてはいけません。
• モデルの確認、費用の相談、API フラグは、最終的な画像プロンプトと分けてください。タスクに役立つ場合にのみ、以下のモデル固有の参照画像手順を使用してください。ユーザーの正確なテキスト、意図する内容、参照画像の対象、編集時に維持すべき条件を保持してください。プロンプトを大幅に変更する前に確認を得てください。
• ユーザーが複数を依頼していない限り、生成する画像は 1 枚にしてください。モデルを黙って切り替えたり、プロンプトの内容を変更したり、モデル／プロンプトのバリエーションや比較を複数実行したりしないでください。有料の追加バリエーションを生成する前に確認してください。同一プロンプトでの比較が許可されている場合、ユーザーが変更を求めない限り、プロンプト、サイズ、品質を同一にしてください。
• パラメーターの対応状況や検証状況を確認する必要がある場合は、references/models.md を参照してください。無効なモデル、アクセス／403、クォータ、またはポリシーによるエラーが発生した場合は、エラーを報告して停止してください。モデルを切り替えたり、プロンプトを書き換えたりして自動的に再試行しないでください。

CLI の解決

優先して呼び出す順序：

# Existing CLI on PATH
gpt-image --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Installed skill folder; use runtime-provided skill path when available
uv run "$SKILL_DIR/scripts/generate.py" --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Direct transient CLI when the user requested setup/one-off CLI execution
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image --model MODEL_ID -p "PROMPT" [options]

scripts/generate.py はランチャーです。リポジトリ内の src/gpt_image_cli → インストール済みの gpt-image → PATH 上の gpt-image → 一時的な uvx／uv フォールバックの順に使用します。

キーとコストのルール

• CLI は、既存の環境変数を上書きせず、プロセス環境変数、次に .env、次に ~/.env から OPENAI_API_KEY を読み込みます。API 呼び出しが成功すると、ユーザーの OpenAI アカウントに課金されることがあります。
• ホスト／ランタイムにプラットフォーム管理のネイティブな画像生成機能があり、ユーザーがその方法を希望する場合は、この CLI ではなくホストのツールを使用します。
• OPENAI_API_KEY が設定されていない場合は、キーがないことを伝えるか、ユーザーが希望している場合はホストネイティブの生成機能を使用します。シークレットを書き込まないでください。
• ユーザーがローカルキーの使用を避けたい場合は、unset OPENAI_API_KEY を尊重してください。.env／~/.env にキーがある場合は、回避策を講じるのではなく、そのセッション中は削除または名前を変更するよう伝えてください。
• シークレットの値は絶対に表示しないでください。

フラグ

フラグ	値	用途
-p, --prompt	string	必須のプロンプト／編集指示
-f, --file	path	出力先のパス。省略時は自動で名前が付けられます
-i, --image	repeatable path	編集エンドポイントを使用します。複数の参照に対応します
-m, --mask	PNG path	アルファマスクを使用してインペイントします。-i が必要です
--model	gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst	エージェントは解決済みの選択肢を明示的に渡す必要があります
--size	1k、2k、4k、portrait、landscape、square、wide、tall、またはリテラル値	キャンバスサイズ
--quality	low、medium、high、auto。2.5 では xhigh、max も指定可能	コスト／品質の調整。モデル固有の制限を確認してください
-n, --n	integer	画像の枚数
--background	auto、opaque。2.5 では transparent も指定可能	透過には PNG または WebP が必要です。JPEG は使用できません
--input-fidelity	low、high。デフォルトでは省略	編集時のみ使用します。2.5 の値を明示した場合は API に渡されますが、サポートされているとは限りません
--moderation	auto、low	生成時のモデレーション設定
--format	png、jpeg、webp	出力エンコーディング
--compression	0-100	JPEG／WebP の圧縮率
--user	string	任意のエンドユーザー識別子

品質設定の目安（保証ではありません。ユーザーと合意した設定を維持してください）。2.5 では、古い制作ガイドに記載された固定の品質に関する助言よりも、以下を優先します。

• low：低コストのドラフトや幅広い探索に適しています。複数のバリエーションにはユーザーの許可が必要です。
• medium：通常の探索、スタイルの検討、コストと品質のバランスに適しています。
• high：CLI のデフォルトであり、最終素材、文字量の多い画像、図表、UI の候補となります。2.5 ではタスク要件に照らして評価してください。medium では不十分だと決めつけたり、設定を上げれば必ず良くなると考えたりしないでください。
• xhigh／max：より高品質な制作に使える 2.5 専用オプションです。すでに合意した品質設定を上げる場合は、コストとのトレードオフを事前に相談してください。予算を重視するリクエストでは自動的に使用しないでください。

サイズの方針：

• デフォルト／SNS 用の正方形：1k／1024x1024
• ポスター／モバイル／美容：portrait
• 風景／ゲームプレイ／写真：landscape
• 印刷物／紙面の図：2k
• ワイドスクリーンのヒーロー画像：4k
• 縦型ストーリー／バナー：tall

エンドポイントの振り分け

モード	条件	エンドポイント
テキストから画像を生成	-i なし	/v1/images/generations
参照画像の編集	-i を 1 つ以上指定	/v1/images/edits
インペイント	-i と -m を指定	マスクを指定して /v1/images/edits

デバッグに十分な形で API エラーをそのまま表示します。終了コード：0 は成功、1 は API エラー／拒否、2 は引数の誤り／キー不足です。

リファレンスの読み込み

• Image 2: references/gallery.md を開き、続いて一致する references/gallery-*.md カテゴリを 1 つと、その実際のプロンプトテキストを開きます。必要に応じて references/craft.md または過去の references/openai-cookbook.md の関連セクションのみを読んでください。
• Image 2.5: 正確なブリーフには必須のリファレンスはありません。ガイダンスが必要な場合は、次のいずれかを1 つ直接選んでください: references/openai-image-2.5-generation.md（写真/製品/イラスト）、references/openai-image-2.5-layout-and-text.md（テキスト/UI/図/パネル）、または references/openai-image-2.5-editing.md（リファレンス/マスク/翻訳）。
• その他の質問: references/openai-image-2.5.md は任意のインデックスです。references/openai-image-2.5-migration.md は移行/比較を扱います。references/models.md は現在の API パラメータと検証ステータスを管理します。
• 追加のインスピレーションのみ: ギャラリーのケース、対象を絞った craft セクション、または references/templates-gpt-image-2.5.md（コミュニティによる適応であり、検証済みの出力ではありません）。これらや、2.5 向けの古い Cookbook を事前に読み込まないでください。

両方のモデルルートではなく、最小限の有用なスライスを読み込んでください。真にハイブリッドな場合にのみ、2 つ目のタスクスライスを追加してください。過去の例は、現在の API ノートやユーザーのモデル/設定より優先されるものではありません。

検証

• API 呼び出しの前: 解決されたモデルと明示的な --model、エンドポイントモード、サイズ、品質、出力パス、および必要なリファレンス/マスクファイルを確認してください。明示的に必要でない限り --input-fidelity は省略してください。2.5 が常に high を使用または受け入れると想定しないでください。
• CLI 呼び出しの後: CLI が出力したパスを報告し、失敗時には stderr を表面化させてください。
• 編集/インペイントの場合: -i のパスが存在することを確認してください。使用時には -m が存在することを確認してください。

例を適応する際は、Curated と Author + Source のメタデータを保持してください。新しく収集したプロンプトは、README への昇格の前に Reference Gallery に追加してください。