gpt-imagegen

GPT ImageGen

設定済みの OpenAI 互換 Images API エンドポイントを通じて、テキストからの画像生成、画像編集、画像の最適化、マスクを使った編集、複数画像の合成を行うには、scripts/generate_image.py を使用してください。

ローカルで PNG キャンバスを扱う（サイズ変更、分割、結合、ディテールの転写、スコアリング、シャープ化、4K／タイルの実験）には、scripts/tile_canvas.py を使用してください。

4K、ズーム可能なテクスチャ、タイル生成、継ぎ目の修復、アップスケーリングのワークフローについては、タイルを生成または編集する前に references/4k_workflows.md をお読みください。

クイックスタート

初回使用時または設定変更後に、環境チェックを実行してください。

python3 scripts/check_environment.py

このスキルには Python 3.9 以降が必要です。Python 3.10 以降を推奨します。サードパーティ製の Python 依存関係はなく、設定済みの HTTPS API エンドポイントが必要です。

設定ファイルがない場合：

python3 scripts/check_environment.py \
  --write-config \
  --base-url "https://examine.com" \
  --api-key "YOUR_API_KEY"

通常のテキストからの画像生成：

python3 scripts/generate_image.py \
  --prompt "A cinematic rainy Shanghai street at night, neon reflections, vintage taxi" \
  --output ./generated-image.png

画像を 1 枚編集または最適化する：

python3 scripts/generate_image.py \
  --image ./source.png \
  --prompt "Improve clarity, restore detail, keep the original composition natural" \
  --output ./optimized-image.png

複数の画像を合成する：

python3 scripts/generate_image.py \
  --image ./person.png \
  --image ./background.png \
  --prompt "Place the person naturally into the background, matching lighting and perspective" \
  --output ./composited-image.png

関連するバリエーションを少数まとめて生成する：

python3 scripts/generate_image.py \
  --prompt "Four premium packaging concepts for a jasmine tea brand, same art direction, different label layouts" \
  --count 4 \
  --output ./tea-variant.png

透過アセットを生成する：

python3 scripts/generate_image.py \
  --prompt "A ceramic tea cup, isolated with a transparent background" \
  --background transparent \
  --output-format png \
  --output ./tea-cup.png

ネイティブ 4K をリクエストする（2560x1440 を超えるサイズでは実験的）：

python3 scripts/generate_image.py \
  --prompt "A detailed panoramic mountain landscape at sunrise" \
  --size 3840x2160 \
  --quality xhigh \
  --output ./landscape-4k.png

生成スクリプトのデフォルト設定：

• テキストからの画像生成モデル：gpt-image-2.5-flare
• 編集／参照／合成モデル：--image が指定されている場合に選択される gpt-image-2.5-sunburst
• 明示的に指定した --model は、ドキュメントに記載されている 2026-09-08 スナップショットも含め、いずれのデフォルトよりも優先されます
• サイズ：1024x1024
• 品質：high（このスキルの既存のデフォルト。API 自体のデフォルトは auto です）
• タイムアウト：300 秒
• 転送方式：非ストリーミング JSON。公式の SSE イベントフローを意図的にリクエストする場合にのみ --stream を使用してください

互換性ゲート

リクエストフィールドの正確な情報源として、OpenAI 公式の Images API ガイド／リファレンスを使用してください。最終確認日：2026-09-25。

• 画像生成ガイド：モデルの機能、カスタムサイズ、透明度、品質。
• 画像の作成：JSON 形式の生成パラメーター。
• 画像の編集：マルチパート形式の編集パラメーター。

サードパーティの互換プロバイダーや、認識されていないモデルエイリアスから、サポート状況を推測しないでください。プロバイダーの対応は公式 API より遅れることがあります。サポートされていないモデルやパラメーターは、モデルを黙って切り替えたり、ネイティブ出力をリサイズで置き換えたりせずに報告してください。

各リクエストの前に、次の点を確認してください。

• 選択したリクエスト形式で文書化されているフィールドのみを送信してください。
• GPT Image 2.5 の両モデルと 2026-09-08 スナップショットでは、auto またはカスタムの WIDTHxHEIGHT がサポートされています。縦横の各辺は 16 の倍数で、いずれも 3840 以下、アスペクト比は 1:3〜3:1、総ピクセル数は 655,360 以上 8,294,400 以下である必要があります。
• 3840x2160 と 2160x3840 は有効なネイティブリクエストです。2560x1440 を超える解像度は実験的です。4096x4096 と 4096x2160 は文書化された上限を超えます。
• GPT Image 2.5 は、auto、low、medium、high、xhigh、max の品質をサポートしています。以前のモデルでは xhigh と max はサポートされていません。
• 透明な出力には、PNG または WebP とともに --background transparent が必要です。形式が省略された場合、スクリプトは PNG を選択し、JPEG は拒否します。出力ファイル名の拡張子は、選択した形式に合わせてください。
• gpt-image-2 とその 2026-04-21 スナップショットも、同じ上限の範囲でカスタムサイズをサポートしています。透明な背景はプレビュー版です。これらのモデルでは入力忠実度が自動的に高く設定されるため、--input-fidelity は省略してください。
• --input-fidelity は編集専用であり、GPT Image 2.5 では引き続き任意です。現在の Images API リファレンスでは、--moderation は生成専用です。
• --output-compression 0-100 には、JPEG または WebP が必要です。
• --count は 10 以下にしてください。
• --resize-output は、有効な API サイズでの出力後に、ローカルで PNG を明示的にリサイズする場合にのみ使用してください。無効なネイティブサイズは失敗し、黙ってリサイズ済みの 1024x1024 画像にフォールバックすることはありません。
• --stream は意図的に使用する場合にのみ指定してください。デフォルトでは非ストリーミングです。

機能についてはガイドを、リクエストフィールドについてはエンドポイントリファレンスを参照してください。リファレンスの stream: false シグネチャは、非ストリーミングのオーバーロードを示します。ストリーミングでは、ガイドの SSE フローを使用します。

設定ゲート

このスキルが呼び出されたら、生成を試みる前に API が設定されていることを確認してください。

1. 新規インストールでは、scripts/check_environment.py を優先して使用してください。
2. HTTPS API のベース URL には、GPT_IMAGE_BASE_URL または --base-url を使用してください。
3. API キーには、GPT_IMAGE_API_KEY または --api-key を使用してください。
4. baseUrl または apiKey が存在しないか空の場合は、処理を中止し、正しい設定をユーザーに尋ねてください。
5. 認証情報を捏造したり、API キーを表示したり、実際のリクエストにプレースホルダーを使用したり、空のキーのまま処理を続けたりしないでください。

設定ファイルのパス：

• macOS/Linux：~/.config/gpt-imagegen/config.json
• Windows：%APPDATA%\gpt-imagegen\config.json

従来の DCHA_IMAGE_* 環境変数と設定ファイルは、移行用のフォールバックとして使用できます。

ワークフロー

1. ユーザーが --raw-prompt を付けてそのまま渡すよう明示的に依頼した場合を除き、リクエストを洗練された英語の画像プロンプトに変換します。
2. 重要なスタイル、被写体、構図、アスペクト比、テキスト、色、雰囲気、参照画像に関する制約を維持します。
3. API を呼び出す前に、毎回互換性ゲートを実行します。
4. 現在のワークスペースまたはユーザー指定のフォルダー内に、安定した出力パスを選びます。
5. テキストから画像を生成する場合は、generate_image.py --prompt ... --output ... を呼び出します。
6. 編集、最適化、修復、または高画質化の場合は、--image でソースを渡します。
7. 複数画像を合成する場合は、ソースごとに --image を繰り返します。
8. 部分編集の場合は、--mask を渡します。マスクは最初の --image に適用されます。
9. 関連性の高い少数の画像をまとめて生成する場合は --count 2-4 を使用します。大規模なストーリーボードや独立したパネルは、ファイル名に一貫性を持たせたうえで複数のリクエストに分けます。
10. 再試行可能な通信障害が発生した場合は、まずプロンプトと参照入力を維持して、同じ形式のリクエストを再試行します。
11. コンテンツまたはモデレーションのエラーが発生した場合、ユーザーの目的が許可されているときは、正確でより安全な表現にプロンプトを一度修正します。
12. 出力パスを返します。ホスト側でローカルファイルを表示できる場合は、生成された画像を表示します。

4K とアップスケーリング

4K、高いピクセル密度、拡大して確認できるテクスチャ、タイル生成、継ぎ目の修復、または「放大后能看到细节」を含むリクエストでは、references/4k_workflows.md を読み込みます。

新しい 4K 画像には、ネイティブの --size 3840x2160 リクエストを優先します。編集の場合は --image を追加し、同じサイズを指定して Sunburst を使用します。この解像度は実験的なものであることを説明し、納品前に返された画像の寸法と 100％ 表示の切り抜きを確認します。

単純なリサイズでは本物のディテールは生まれません。ネイティブの結果が得られない場合、またはタスクの要件を満たさない場合に限り、ローカルでのリサイズ、画像全体の超解像、または既存のタイル処理ワークフローを使用します。参照資料には、代替手段として過去のタイル処理の実験内容が記載されています。

透過画像では、出力にアルファチャンネルと透明ピクセルが含まれていることを確認します。画像に描き込まれた市松模様や白い背景は、透過ではありません。

失敗時のプロンプトの明確化

リクエストが曖昧、または安全でないと解釈された可能性が高いことが原因で生成に失敗した場合は、創作上の目的を維持しながら、正確な文脈とより安全な表現を加えてプロンプトを改善します。

• 親密な場面やロマンチックな場面：同意した成人であること、露骨でない表現、品のあるエディトリアルポートレート／ファッションの表現を指定し、明確に許可されていない限り、ヌードや性的行為を含めないようにします。
• 若く見えるキャラクターやファンアートのキャラクター：性的な表現を避けます。適切な場合は、成熟した被写体を成人版または成人のオリジナルキャラクターとして描写します。
• 写実的なポートレートや写真：必要に応じて、架空の設定、演出された場面、エディトリアル、ファッション、コスプレ、または個人的なポートレートを意図していることを明確にします。
• ブランド、製品、ロゴ、フランチャイズ：事実に合致する場合は、非公式のファンアート、パロディ、トリビュート、コンセプトデザイン、または個人利用／非営利利用であることを明確にします。
• 公人や実在の人物：誤解を招かないプロンプトにし、センシティブ、屈辱的、性的、または誤解を招く描写を避けます。
• 暴力、負傷、ホラーの美的表現：正確な場合は、様式化された表現、映画的な演出、ファンタジー、舞台メイク、小道具のデザイン、ゲームアート、または架空の場面として表現します。

曖昧または刺激の強い言葉より、視覚的に正確な表現を優先します。

透かしポリシー

通常のオリジナル画像、一般的なイラスト、商品写真、風景、コンセプトアート、架空のポートレート、無害なファンスタイルの場面には、架空であることを示す透かしを付けないのがデフォルトです。

混乱や誤用のリスクを実質的に低減できる場合に限り、「Fictional dramatization」という控えめな小さなキャプションを追加します。対象となる例は、パロディ／デマ／なりすましの依頼、偽ニュースやドキュメンタリー風の写実表現、公人や実在の人物を誤解させる描写です。

通常の、誤解を招かない制作には --fictional-watermark never を使用します。--fictional-watermark always は、架空であることを示す必要性が高い状況に限って使用します。

URL の安全性

リモート画像、マスク、生成画像、リダイレクト、API ベース URL はすべて HTTPS を使用する必要があります。スクリプトは、HTTP を使用する URL、認証情報を含む URL、ホスト名がない URL、localhost を指す URL、.local ホスト名を使用する URL、またはプライベート／リンクローカル／ループバック／予約済み／グローバルでない IP アドレスのリテラルを指す URL を拒否します。ユーザーが指定した画像 URL とマスク URL は DNS チェックされ、ブロック対象のアドレスに解決される場合は拒否されます。

設定済みの API ベース URL は HTTPS を使用する必要があります。設定済み API ドメインに対する DNS のパブリックアドレス検証は緩和されているため、プロキシ経由のプロバイダードメインを使用できます。

スクリプト一覧

生成／編集オプションの詳細については、python3 scripts/generate_image.py --help を使用してください。

generate_image.py の一般的なオプション：

• --prompt：必須の画像プロンプトです。
• --image：省略可能な入力画像のパスまたは HTTPS URL です。複数画像の合成では、複数回指定できます。
• --mask：局所編集用の省略可能なマスク画像のパスまたは HTTPS URL です。
• --output：出力先のパスです。親ディレクトリは自動的に作成されます。
• --size：互換性ゲートの対象となる auto またはネイティブ寸法です。1536x864、2048x2048、3840x2160 などを指定できます。
• --count：リクエストする最終画像の枚数です。
• --resize-output：未対応の最終寸法に対して、ローカルで最終 PNG のサイズを変更します。
• --quality：auto、low、medium、high、xhigh、max のいずれかです。最後の 2 つは GPT Image 2.5 が必要です。
• --output-format：png、jpeg、webp のいずれかです。
• --output-compression：0-100。JPEG／WebP でのみ使用できます。
• --background：auto、opaque、transparent のいずれかです。透過には PNG／WebP が必要です。
• --moderation：生成時に使用する auto または low です。
• --input-fidelity：GPT Image 2.5 の編集時に省略可能な low または high です。デフォルトでは省略されます。
• --model：自動選択される Flare（生成）／Sunburst（編集）を上書きします。
• --stream／--no-stream：SSE ストリーミングを有効にするか、通常の JSON を使用します。
• --raw-prompt：プロンプトを指定どおりに送信します。
• --fictional-watermark：auto、always、never のいずれかです。
• --retries、--retry-delay、--max-retry-delay：再試行を制御します。

ローカル PNG ヘルパーについては、python3 scripts/tile_canvas.py --help を使用してください。

tile_canvas.py の主なコマンド：

• prepare：PNG を 3840x2160 などのターゲットキャンバスに合わせます。
• split：キャンバスを重なり合うタイルに分割し、manifest.json を書き出します。
• manifest：タイルのサイズとスケール比を要約します。
• stitch：正確な切り抜きタイルを重み付けして結合します。
• stitch-slots：タイル中央の領域のみを結合し、重複部分のコンテキストを破棄します。
• stitch-upscaled-slots：フルサイズで生成されたタイル出力をスーパーサンプリングされたキャンバスに結合します。2x2 では実験的な機能です。
• upscaled-detail-transfer：フルサイズで生成されたタイルから、アップスケールしたベース画像に高周波ディテールを転写します。
• detail-transfer：生成されたタイルのディテールを、同じサイズの安定したベース画像に転写します。
• frequency-composite：ドナー画像から安定したベース画像に、高周波成分を局所的に合成します。
• enhance：決定論的なシャープ化、コントラスト調整、微細な粒状感を適用します。
• score：変更前後の比較用に、エッジ／テクスチャの概算スコアを算出します。
• overlay：選択したタイルをベース画像に貼り付けます。

注意事項

• テキストから画像を生成する呼び出しでは、JSON を使用して /v1/images/generations を呼び出します。
• 編集／合成の呼び出しでは、マルチパートアップロードを使用して /v1/images/edits を呼び出します。
• 複数の画像は、image[] フォームフィールドを繰り返して送信されます。
• ストリーミングでは、公式のイベント形式 image_generation.partial_image、image_edit.partial_image、image_generation.completed、image_edit.completed が想定されています。
• スクリプトは API の生メタデータファイルを書き出しません。JSON サマリーには、選択されたモデル、リクエストした API サイズ、省略可能なローカルサイズ変更、出力パスが含まれます。リクエストしたサイズだけでは、プロバイダーがその解像度を返したことの証明にはなりません。
• API がエラーを返した場合は、ステータスコードとメッセージを要約してから、パラメーターを調整してください。不足情報の確認は、必要な場合に限って求めてください。

モデルのルーティングまたは API の制約を変更した後は、オフラインのリクエスト回帰テストを実行してください。

python3 -m unittest discover -s tests -v