doggy8088/imagegen-mai

Microsoft Foundry MAI-Image の画像生成スキル

Microsoft Foundry の MAI-Image デプロイメントを使用して、現在のプロジェクト向けの画像（例：Webサイトアセット、ゲームアセット、UIモックアップ、製品モックアップ、ワイヤーフレーム、ロゴデザイン、フォトリアルな画像、インフォグラフィック）を生成または編集します。

このファイル内で、<skill-dir> はこの SKILL.md が置かれているディレクトリを意味します。

実行モードとルール

このスキルは、バンドルされた CLI である <skill-dir>/scripts/image_gen.js を使用します。エージェントホストは、このワークフロー用の組み込み画像生成ツールや画像表示ツールを提供しないため、存在しない組み込みツールを参照したり使用しようとしないでください。

CLI は3つのサブコマンドを公開しています：

• generate
• edit
• generate-batch

ルール：

• 通常の画像生成および編集リクエストには scripts/image_gen.js を使用します。
• この CLI は MAI-Image シリーズモデルのみをサポートします。GPT Image、DALL-E、または他のモデルを経由させないでください。
• デフォルトのデプロイメントは IMAGEGEN_MAI_IMAGE_DEPLOYMENT、または未設定の場合は MAI-Image-2.6-Flash です。ユーザーに明示的に要求されない限り、異なるデプロイメントに静かに切り替えないでください。まずユーザーに確認してください。
• MAI 画像モデルは常に不透明な PNG を返します。透明画像が必要な場合は、以下のクロマキーワークフローを使用し、カットアウトがローカルで行われたことをユーザーに伝えてください。
• batch という単語だけでは generate-batch が必要になるわけではありません。マルチアセットリクエストが自然に JSONL バッチとして表現される場合に generate-batch を使用してください。それ以外の場合は個別の CLI コマンドを実行します。
• ライブ API 呼び出しには MAI の認証情報とネットワークアクセスが必要です。
• バンドルされた scripts/image_gen.js ワークフローを使用してください。単発の SDK ランナーを作成しないでください。
• scripts/image_gen.js を決して変更しないでください。何か不足している場合は、他のことをする前にまずユーザーに確認してください。

出力ポリシー：

• 生成されたアセットは、要求されたパスに直接書き込むか、ユーザーがパスを指定しなかった場合は output/imagegen/ に書き込みます。
• 画像が現在のプロジェクト用である場合、最終的に選択された画像をワークスペースに保存してから終了します。
• ユーザーが明示的に置き換えを要求しない限り、既存のアセットを上書きしないでください。代わりに、hero-v2.png や item-icon-edited.png のようにバージョン管理されたファイル名を作成します。

共有プロンプトガイダンスは references/prompting.md と references/sample-prompts.md にあります。

CLI ドキュメント/リソース：

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.js

ローカル後処理ヘルパー：

• <skill-dir>/scripts/remove_chroma_key.js：生成された画像からフラットなクロマキー背景を除去し、アルファチャンネル付きの PNG を書き込みます。アンチエイリアスエッジには、自動キーサンプリング、ソフトマット、デスピルを推奨します。

使用する場合

• 新しい画像（コンセプトアート、商品写真、カバー、Webサイトヒーロー、ポスター）を生成する
• 現在の実世界の情報に依存する新しい画像を生成する（--web-grounding を使用）
• 既存の画像を編集する（オブジェクトの削除または置換、属性変更、インペインティング、テキスト更新、照明または天候の変更、アーティファクトのクリーンアップ）
• 最大5つの参照画像を1つの結果に合成する（製品、キャラクター、ブランドアセットの一貫性を保つため）
• 1つのタスクに対して多数のアセットまたはバリアントを生成する

使用しない場合

• リポジトリ内の既存の SVG/ベクターアイコンセット、ロゴシステム、またはイラストライブラリを拡張または一致させる場合
• SVG、HTML/CSS、またはキャンバスで直接生成する方が適切な単純な形状、図、ワイヤーフレーム、アイコンを作成する場合
• ソースファイルが編集可能なネイティブ形式で既に存在する場合の、小規模なプロジェクトローカルアセットの編集
• ユーザーが生成されたビットマップではなく、決定論的なコードネイティブ出力を明確に望んでいるタスク
• 出力が約1.5Kより大きい場合（MAI-Image-2.6 の上限は 2,359,296 ピクセル、例えば 1536x1536）。静かにアップスケーリングする代わりに、ユーザーに制限を伝えてください。

決定木

2つの別々の質問を考えてください：

1. 意図：これは新しい画像ですか、それとも既存の画像の編集ですか？
2. 実行戦略：これは1つのアセットですか、それとも多数のアセット/バリアントですか？

意図：

• ユーザーが既存の画像を変更しつつ一部を保持したい場合、リクエストを edit として扱います。
• ユーザーが参照用の画像を提供し（スタイル、構図、雰囲気、被写体）、それらを結果に反映させたい場合、それらの画像を参照として edit を使用します（MAI 生成 API は画像を受け付けません）。
• ユーザーが画像を提供しない場合、リクエストを generate として扱います。

編集のセマンティクス：

• CLI の編集モードは、繰り返し --image フラグを使用して、1～5個のローカル PNG または JPEG ファイルを受け入れます。
• ユーザーが会話から添付画像や参照を提供した場合、環境がサポートしていれば最初にそれらをローカルに保存します。そうでなければ、ユーザーにローカルファイルパスを尋ねてください。
• 画像の順序は重要なので、プロンプト内で各画像をインデックスと役割でラベル付けしてください。
• 編集の場合、不変条件を積極的に保護し、デフォルトで非破壊的に保存します。
• 編集は MAI-Image-2 および MAI-Image-2e ではドキュメント化されておらず、CLI はそれらをブロックします。編集には MAI-Image-2.5 または MAI-Image-2.6 デプロイメントを使用してください。

実行戦略：

• 多数のプロンプト/アセットに対して、JSONL バッチが最も明確なワークフローである場合、CLI generate-batch サブコマンドを使用します。
• MAI API はリクエストごとに1つの画像を返し、n パラメータはありません。バリアントの場合は、異なる out 名を指定して別々のコマンドまたは別々のバッチジョブを実行します。
• レート制限は低いです（例：Tier 1 の MAI-Image-2.6-Flash で1分あたり6リクエスト）。ユーザーが自分のクォータを把握していない限り、--concurrency はデフォルトの2のままにします。

ユーザーが既存の画像を変更することを明確に求めない限り、新しい画像を求めていると仮定します。

ワークフロー

1. CLI サブコマンドを決定します：generate、edit、または generate-batch。
2. 出力がプレビューのみか、現在のプロジェクトで消費されるものかを決定します。
3. 実行戦略を決定します：単一アセット vs 繰り返し CLI コマンド vs CLI generate-batch。
4. 入力を事前に収集します：プロンプト、正確なテキスト（そのまま）、制約/回避リスト、ターゲットサイズまたはアスペクト比、および入力画像。
5. すべての入力画像について、その役割を明示的にラベル付けします：
   • 参照画像
   • 編集ターゲット
   • サポートする挿入/スタイル/合成入力
6. ユーザーが写真、イラスト、スプライト、商品画像、バナー、またはその他の明示的にラスタースタイルのアセットを要求した場合、SVG/HTML/CSS プレースホルダーに置き換えるのではなく、このスキルを使用します。リクエストが既存のリポジトリネイティブ SVG/ベクター/コードアセットと一致する必要があるアイコン、ロゴ、UI グラフィックの場合、代わりにそれらを直接編集することを優先します。
7. プロンプトを具体性に基づいて拡張します：
   • ユーザーのプロンプトがすでに具体的で詳細である場合、創造的な要件を追加せずに、明確な仕様に正規化します。
   • ユーザーのプロンプトが一般的である場合、出力品質を実質的に向上させる場合にのみ、適切な拡張を追加します。
8. サイズを選択します。既知のターゲットには --size WIDTHxHEIGHT を使用し、構図が決定する場合（MAI-Image-2.6 ファミリー）は --auto-aspect-ratio を使用します。プロンプトが現在の実世界のエンティティ、場所、イベントに依存する場合（MAI-Image-2.6 ファミリー）は --web-grounding を追加します。
9. デフォルトのデプロイメントで scripts/image_gen.js を実行します。
10. 透明出力リクエストの場合、以下のクロマキーワークフローに従います。
11. 出力を検査し、検証します：被写体、スタイル、構図、テキストの正確さ、および不変条件/回避アイテム。
12. 単一のターゲットを絞った変更で繰り返し、再確認します。
13. プレビューのみの作業の場合、ユーザーが別の場所を要求しない限り、output/imagegen/ に書き込みます。
14. プロジェクトに紐づく作業の場合、成果物をワークスペースに書き込み、消費するコードや参照を更新します。
15. バッチまたはマルチアセットリクエストの場合、ユーザーが明示的に出力をプレビューのみにしておくよう要求しない限り、要求されたすべての成果物の最終版をワークスペースに保存します。破棄されたバリアントは、要求がない限り保持する必要はありません。
16. デプロイメント、サイズ、auto_aspect_ratio、web_grounding、出力パス、ネットワーク設定については CLI ドキュメントを参照してください。
17. ワークスペースに保存されたアセットの最終保存パスと、最終的なプロンプトまたはプロンプトセットを常に報告してください。

透明画像リクエスト

MAI 画像モデルは常に不透明な PNG を返し、透明背景オプションはありません。クロマキーソース画像とローカル除去を使用して透明アセットを作成します。

手順：

1. scripts/image_gen.js generate（または既存画像の場合は edit）を使用して、要求された被写体を完全にフラットな単色クロマキー背景上に配置します。

2. 被写体に現れる可能性が低いキーカラーを選択します：デフォルト #00ff00、緑色の被写体には #ff00ff を使用し、青色の被写体には #0000ff を避けます。

3. クロマキーソース画像をワークスペースまたは tmp/imagegen/ に保持します。

4. バンドルされたヘルパーを実行します：

   node "<skill-dir>/scripts/remove_chroma_key.js" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. 出力にアルファチャンネル、透明なコーナー、妥当な被写体カバレッジ、および目に見えるキーカラーフリンジがないことを検証します。明るい背景と暗い背景の上に合成し、ハローをチェックします。細いフリンジが残っている場合は、--edge-contract 1 で1回再試行します。エッジが視覚的に階段状になっており、被写体が光沢のある反射性のものでない場合にのみ --edge-feather 0.25 を使用します。

6. アセットがプロジェクトに紐づく場合、最終的なアルファ PNG をプロジェクトに保存します。

以下のようにクロマキーリクエストをプロンプトします：

背景除去のため、完全にフラットな単色 #00ff00 クロマキー背景上に要求された被写体を作成してください。
背景は、影、グラデーション、テクスチャ、反射、床面、照明のバリエーションがない、均一な単色でなければなりません。
被写体は背景から完全に分離し、くっきりとしたエッジと十分なパディングを維持してください。
被写体内のどこにも #00ff00 を使用しないでください。
明示的に要求されない限り、キャストシャドウ、コンタクトシャドウ、反射、ウォーターマーク、テキストは一切使用しないでください。

クロマキー処理は、髪の毛、毛皮、羽、煙、ガラス、液体、半透明素材、反射性オブジェクト、ソフトシャドウには適していません。これらの被写体についてクリーンなカットアウトを約束する前に、この制限についてユーザーに伝えてください。

プロンプト拡張

ユーザープロンプトを構造化された、プロダクション指向の仕様に再フォーマットします。ユーザーの目標をより明確にし、実行可能にしますが、盲目的に詳細を追加しないでください。

これをプロンプト整形ガイダンスとして扱い、閉じたスキーマとしては扱いません。役立つ行のみを使用し、明確さを実質的に向上させる場合にのみ、短い追加のラベル付き行を追加してください。

具体性ポリシー

ユーザープロンプトの具体性に基づいて、どれだけ拡張するかを決定します：

• プロンプトがすでに具体的で詳細である場合、その具体性を保持し、正規化/構造化のみを行います。
• プロンプトが一般的である場合、結果を実質的に向上させる場合にのみ、適切な拡張を追加しても構いません。

許可される拡張：

• 構図またはフレーミングのヒント
• 仕上げレベルまたは使用目的のヒント
• 実用的なレイアウトガイダンス
• 要求をサポートする合理的なシーン具体性

許可されない拡張：

• 要求に暗に含まれていない余分なキャラクターやオブジェクト
• 暗に含まれていないブランド名、スローガン、パレット、ナラティブビート
• 周囲のレイアウトがサポートしない限り、任意のサイド固有の配置

ユースケース分類（正確なスラッグ）

各リクエストを以下のバケットのいずれかに分類し、プロンプトと参照間でスラッグを一貫させてください。

生成：

• photorealistic-natural: リアルなテクスチャと自然光を使用した、カジュアル/エディトリアルなライフスタイルシーン。
• product-mockup: 製品/パッケージショット、カタログ画像、マーチャンダイズコンセプト。
• ui-mockup: アプリ/Webインターフェースのモックアップとワイヤーフレーム；希望する忠実度を指定します。
• infographic-diagram: 構造化されたレイアウトとテキストを使用した図/インフォグラフィック。
• scientific-educational: 教室用説明図、科学図、および必要なラベルと正確性の制約を持つ学習用ビジュアル。
• ads-marketing: キャンペーンコンセプトと広告クリエイティブ。オーディエンス、ブランドポジション、シーン、正確なタグライン/コピーを指定。
• productivity-visual: スライド、チャート、ワークフロー、データ重視のビジネスビジュアル。
• logo-brand: ロゴ/マークの探索、ベクター向き。
• illustration-story: 漫画、児童書アート、ナラティブシーン。
• stylized-concept: スタイル主導のコンセプトアート、3D/スタイライズドレンダー。
• historical-scene: 時代に正確な/世界知識を要するシーン。

編集：

• text-localization: 画像内テキストの翻訳/置換、レイアウトを保持。
• identity-preserve: 試着、人物シーン；顔/体/ポーズを固定。
• precise-object-edit: 特定の要素の削除/置換（内部の交換を含む）。
• lighting-weather: 時間帯/季節/雰囲気の変更のみ。
• background-extraction: フラットなクロマキー背景と scripts/remove_chroma_key.js を使用したローカル除去によるクリーンなカットアウト。
• style-transfer: 被写体/シーンを変更しながら参照スタイルを適用。
• compositing: マルチイメージの挿入/マージ。照明と遠近法を一致させる（最大5画像）。
• sketch-to-render: ドローイング/線画からフォトリアルレンダーへ。

共有プロンプトスキーマ

両方のトップレベルモードに対して、以下のラベル付き仕様を共有プロンプトフレームワークとして使用します：

ユースケース: <分類スラッグ>
アセットタイプ: <アセットが使用される場所>
主要リクエスト: <ユーザーのメインプロンプト>
入力画像: <画像1: 役割; 画像2: 役割> (オプション)
シーン/背景: <環境>
被写体: <主な被写体>
スタイル/メディア: <写真/イラスト/3Dなど>
構図/フレーミング: <ワイド/クローズ/トップダウン; 配置>
照明/雰囲気: <照明 + 雰囲気>
カラーパレット: <パレットメモ>
マテリアル/テクスチャ: <表面の詳細>
テキスト (そのまま): "<正確なテキスト>"
制約: <維持すべきもの/避けるべきもの>
回避: <ネガティブ制約>

注意：

• アセットタイプ と 入力画像 はプロンプトフレームワークであり、専用の CLI フラグではありません。
• シーン/背景 は視覚的な設定を指します。
• サイズ、auto_aspect_ratio、web_grounding、出力パスなどの実行に関する注意は、プロンプトテキストではなく CLI パスに属します。

拡張ルール：

• 簡潔に保ちます。
• プロンプトを実質的に向上させるために必要な詳細のみを追加します。
• 編集の場合、不変条件を明示的にリストします（変更するのは X のみ；Y は変更しない）。
• 重大な詳細が不足しており成功を妨げる場合、質問してください。それ以外の場合は続行します。

例

…

[翻訳のために省略]