generating-images

画像の生成（OpenAI gpt-image-2）

ユーザーが画像の生成または編集を依頼した場合は、いつでもこのスキルを使用してください。Python スクリプトを介して OpenAI の gpt-image-2 モデルを利用します。テキストのみのプロンプトと、1 枚以上の参照画像に対応しており、生成した PNG／JPEG／WebP をディスクに保存します。

絶対に守るルール（違反禁止）

1. 必ず gpt-image-2 を使用してください。 gpt-image-1、dall-e-3、その他のモデルに切り替えてはいけません。このため、スクリプトには --model フラグがありません。
2. エラーが発生したら、すぐに処理を中止してください。 再試行したり、モデルを切り替えたり、認証情報がない状態を回避しようとしたり、品質を黙って低下させたりしてはいけません。スクリプトがゼロ以外の終了コードを返した場合は、エラーをそのままユーザーに提示して停止してください。
3. ユーザーから明示的に指示されない限り、.env ファイルや 1Password などから読み取って、OPENAI_API_KEY の不足を「修正」してはいけません。 環境変数が設定されていない場合は、ユーザーにどのように設定するか（または export するか）を尋ねてから、処理を停止してください。

使用する場合

• ユーザーが生成画像（アイコン、ロゴ、イラスト、モックアップ、OG 画像、ブログのヒーロー画像、マーケティング素材、コンセプトアート、図解など）を依頼した場合。
• ユーザーが 1 枚以上の画像を提供し、編集、スタイル変更、合成、または参照画像としての使用を依頼した場合。
• ユーザーが画像の一部の削除や置き換えを依頼した場合（--mask を使用）。

このスキルを使用しない場合：

• グラフ／プロット／データビジュアライゼーション（代わりにコードで生成してください）。
• 既存の写真の調達（利用可能であれば、ストックフォト用のスキルを使用してください）。
• ユーザーのアプリのスクリーンショット（利用可能であれば、スクリーンショット用のスキルを使用してください）。

前提条件

1. OpenAI API キー

環境に OPENAI_API_KEY をエクスポートしておく必要があります。キーは platform.openai.com/api-keys で取得してください。

このスキルには、SKILL.md と同じ場所に .env.example が含まれています。コピーしてキーを入力してください。

cp .env.example .env
# then edit .env and put your real key in

次に、スクリプトを実行する前にキーをエクスポートしてください。

set -a && source .env && set +a

または、シェルから直接エクスポートしてください。

export OPENAI_API_KEY="sk-..."

OPENAI_API_KEY が設定されていない場合、スクリプトは直ちにコード 2 で終了します。ユーザーの明示的な許可なしに、ほかの場所から読み取ろうとしてはいけません。

2. 組織の認証

OpenAI 組織で gpt-image-2 を使用するには、次のページで認証を受ける必要があります。 platform.openai.com/settings/organization/general。 「organization must be verified」と記載された 403 エラーが表示された場合は、その内容を提示して停止してください。モデルを切り替えてはいけません。

3. Python の依存関係

pip install --upgrade openai

スクリプトの場所

Python スクリプトは SKILL.md と同じ場所の scripts/generate_image.py にあります。このスキルが ~/.cursor/skills/generating-images/ にインストールされている場合、スクリプトは ~/.cursor/skills/generating-images/scripts/generate_image.py にあります。

書き込んだ画像の絶対パスを標準出力に表示します。エラーは標準エラー出力に出力され、ゼロ以外の終了コードを返します。スクリプトは最初のエラーが発生した時点で直ちに終了します。

実行方法

必ず Shell ツールを使って実行してください。ユーザーの現在のワークスペース内に、適切な出力先を選んでください（例：Web プロジェクトでは ./public/generated/<slug>.png、それ以外では ./<slug>.png）。

1. テキストから画像を生成

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Minimal flat-vector app icon for a note-taking app, indigo gradient, rounded square, soft shadow" \
  --size 1024x1024 \
  --quality high \
  --out ./icon.png

2. 画像から画像を生成（参照画像 1 枚）

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Restyle this photo as a watercolor painting with warm tones" \
  --image ./photo.jpg \
  --out ./photo-watercolor.png

3. 複数の参照画像

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Photorealistic flat-lay product shot combining all of these items on a white background" \
  --image ./a.png --image ./b.png --image ./c.png \
  --out ./flatlay.png

4. マスク編集（インペインティング）

マスクは最初の入力画像と同じサイズおよび形式で、編集可能な領域を示すアルファチャンネルを含める必要があります。

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Replace the sky with a vivid sunset" \
  --image ./scene.png --mask ./sky-mask.png \
  --out ./scene-sunset.png

5. バッチ／並列モード（一度に多数の異なる画像を生成）

一度に複数の異なる画像を生成する場合（例：ブログのヒーロー画像一式、プロンプトの異なるアイコンのバリエーション数種類、多数のページの OG 画像など）は、スクリプトを N 回実行する代わりに --batch を使います。1 つの Python プロセスからすべてのジョブを並列実行するため、逐次呼び出しよりもはるかに高速で、SDK の起動コストの繰り返しも避けられます。

すべてのジョブを記述した JSON ファイルを作成し、スクリプトを 1 回だけ呼び出します。

cat > /tmp/img-jobs.json <<'EOF'
[
  {
    "prompt": "Minimal flat-vector app icon for a note-taking app, indigo gradient, rounded square",
    "out": "./public/icons/notes.png",
    "size": "1024x1024",
    "quality": "high"
  },
  {
    "prompt": "Photoreal blog hero: a cozy library with warm afternoon light, 5:3 ratio",
    "out": "./public/static/blog/library.png",
    "size": "1600x960",
    "quality": "medium"
  },
  {
    "prompt": "Restyle this product photo as a watercolor painting with warm tones",
    "image": ["./public/products/mug.jpg"],
    "out": "./public/products/mug-watercolor.png"
  }
]
EOF

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --batch /tmp/img-jobs.json --concurrency 5

各ジョブオブジェクトでは、CLI フラグと同じフィールドを指定できます：prompt（必須）、out、size、quality、format、n、image（文字列または文字列の配列）、mask。デフォルト値は単一実行の CLI と同じです。

動作：

• すべてのジョブは --concurrency（デフォルトは 4）で指定した数まで同時に実行されます。妥当な範囲は 3～8 です。OpenAI は組織単位でレート制限を行うため、あまり大きな値にしないでください。
• 正常に書き込まれた画像の絶対パスは、ジョブの完了と同時に標準出力へ 1 行ずつ出力されます。
• ジョブが失敗すると、そのエラーが標準エラー出力に出力され（ERROR: job <i> failed: ...）、残りのジョブが完了した後にスクリプトは終了コード 1 で終了します。他のジョブはキャンセルされません。出力の一部だけが生成されても問題ありません。失敗したジョブだけを再試行できます。
• --batch は --prompt／--image／--mask と同時には使用できません。

並列 Shell 呼び出しよりも --batch を使うべき場合： 同じターンで異なる画像を 2 枚以上生成する場合はいつでも使用してください。このスクリプトを Shell から複数回並列に呼び出さず、代わりに 1 回のバッチ呼び出しを使ってください。

--n と混同しないでください。 --n は 1 回の API 呼び出しで同じプロンプトの複数のバリエーションを生成します（より安価ですが、どれも同じアイデアに基づきます）。--batch は異なるプロンプトを並列で実行します。組み合わせて使うこともできます。バッチ内のジョブで "n": 4 を指定すると、そのプロンプトのバリエーションを 4 つ取得できます。

フラグのリファレンス

フラグ	デフォルト	説明
--prompt	必須*	--batch を使わない場合は必須です。編集時も必ず指定してください。
--image	なし	複数の参照画像を渡すには、複数回指定します。images.edit が実行されます。
--mask	なし	オプションのインペインティング用マスク（アルファ付き PNG）です。
--out	./image.png	出力パスです。--n > 1 の場合はインデックスのサフィックスが追加されます。
--size	auto	1024x1024、1536x1024、1024x1536、2048x2048、3840x2160 など。辺の長さは 16 の倍数である必要があり、最大 3840px、アスペクト比は 3:1 以下です。
--quality	auto	low（高速な下書き）、medium、high（最終アセット）です。
--format	png	png、jpeg、webp です。
--n	1	1 回の呼び出しで同じプロンプトのバリエーションを生成します。
--batch	なし	ジョブオブジェクトの JSON 配列へのパスです。ジョブを並列実行します。
--concurrency	4	--batch モードでの並列ワーカーの最大数です。

意図的に --model フラグはありません。モデルは gpt-image-2 にハードコードされています。

サイズのガイドライン

• アプリアイコン／正方形のサムネイル → 1024x1024
• ランディングページのヒーロー画像／OG 画像 → 1536x1024
• ブログのヒーロー画像（5:3）→ 1600x960（両辺が 16 の倍数、アスペクト比 = 5:3）
• モバイル／縦向きのイラスト → 1024x1536
• マーケティング用ポスター／4K アセット → 3840x2160

品質のガイドライン

• 手早くアイデアを試したり、下書きを作成したりする場合は low（最も安価で高速）を使います。
• medium は適切なデフォルト設定です。
• high は出荷可能な最終アセットに限って使います。大幅に高価で、最大約 2 分かかることがあります。

ユーザーが最終用途を示さずに「画像を生成して」とだけ依頼した場合は、デフォルトで --quality medium を使います。

プロンプト作成のヒント

最良の結果を得るには、プロンプトに次の内容を含めてください。

• 被写体（画像に何を描くか）
• スタイル（フラットなベクター、水彩、フォトリアリスティック、アイソメトリック、線画、3D レンダリングなど）
• 構図／カメラ（クローズアップ、俯瞰、ワイドショット）
• カラーパレット／雰囲気
• 背景（白、グラデーション、風景など。注：gpt-image-2 は透明な背景に対応していません）
• 画像内に表示する必要があるテキスト（引用符で囲みます。gpt-image-2 はテキストを適切に描画します）

ユーザーのプロンプトが曖昧な場合は、本当に判断が難しい場合を除き、聞き返すのではなく、妥当なデフォルトを補って内容を具体化してください。

生成後

1. 出力パスをユーザーに返します。
2. 画像を Markdown に埋め込まないでください。生成されたファイルがワークスペースに書き込まれると、Cursor が自動的に表示します。
3. 結果をウェブサイトやアプリで使用する場合は、ファイルサイズが重要であれば、オプティマイザー（例：pngquant、cwebp）に通すことも検討してください。

生成前にコンテキストを集める

ユーザーが希望する内容（題材、スタイル、配色、サイズ、配置先）を明確に指定していない限り、まず簡単にコンテキストを集めてください。目的は、生成した画像がプロジェクト内で自然になじみ、無関係な素材が突然追加されたように見えないようにすることです。この手順を省くことが、このスキルでブランドイメージにそぐわない結果が生じる最大の原因です。

確認する項目は、おおむね次の順です。

1. 配置先にある類似画像。 画像を public/static/blog/、public/static/marketing/、assets/ などに配置する場合は、Read ツールでそのフォルダー内の既存画像を1〜2点開き、次の要素を合わせます。

   • イラストのスタイル（3D カートゥーン、フラットベクター、フォトリアル、線画、アイソメトリックなど）
   • 配色と照明
   • 題材の傾向（例：「必ず製品のマスコットを登場させる」「比喩を使い、実際のスクリーンショットは使わない」など）
   • アスペクト比と解像度

2. 画像を表示する場所。 関連するファイルを確認します。

   • ブログ記事 → MDX／Markdown を読みます（タイトル、タグ、冒頭の段落、主要な比喩）。
   • ランディングページのセクション → コンポーネント、見出し、周辺のコピーを読みます。
   • README → README の冒頭を読みます。
   • コンポーネント → 何を表しているのかを理解するため、コンポーネントを読みます。

   画像の意味は、ファイル名だけでなく実際のコンテンツから読み取ってください。

3. ブランド／デザイントークン。 プロジェクトで明確に定義された配色、ロゴ、マスコットがあれば、それらを取り入れます。手早く確認できる場所は次のとおりです。

   • tailwind.config.* のブランドカラー
   • globals.css／テーマファイルの CSS 変数
   • ロゴ／マスコットのアセットがある public/
   • 既存の OG 画像やマーケティング用アセット

4. アスペクト比／サイズ。 表示場所に応じて --size を選びます。ブログのヒーロー画像、OG 画像、正方形のアバター、モバイル向けの縦長画像などを想定し、既存の画像に合わせてください。

確認してわかった内容をプロンプトに反映します。コンテンツから題材を選び、類似アセットやブランドトークンからスタイルと配色を決め、表示場所に合わせて構図を整えます。

ユーザーがスタイル、色、具体的な題材を明示している場合は、その指示に従い、コンテキストの収集は省略してください。指示が一部に限られる場合は、指定されていない点についてコンテキストを集めてください。

コードベースから合理的に推測できることについて、ユーザーに確認を求めないでください。まず推測し、実際に判断が難しい場合（例：プロジェクト内に同程度に妥当なスタイルが2種類ある場合）に限って質問してください。

配置して組み込む — ファイルを置くだけにしない

ユーザーから特定の場所（ブログ記事、ランディングページ、OG カード、README、コンポーネントなど）向けの画像を依頼された場合は、PNG を作るだけでなく、作業全体に責任を持ちます。必ず次の順番で行ってください。

1. その場所に適したディスク上の保存先を選びます。既存のファイルを確認し、その慣例に合わせてください。例：

   • ブログのヒーロー画像 → 既存のブログ画像が保存されている場所（例： apps/<app>/public/static/blog/<slug>.png）。
   • ランディングページのアセット → 既存のランディングページ用アセットが保存されている場所（例： apps/<app>/public/static/marketing/...）。
   • README／ドキュメントの画像 → docs/images/、assets/、またはドキュメントと同じ場所。
   • コンポーネント固有のアセット → コンポーネントの隣、またはその public/／assets/ フォルダー。

   ファイル名にはスラッグ、コンポーネント名、またはセクション名を使ってください。既存の命名規則がある場合は、新しい規則を作らないでください。

2. 画像がユーザーの希望した場所に実際に表示されるよう組み込みます。これは必須です。例：

   • ブログ記事の MDX → image:（または同等の）フロントマター項目を更新して、新しいパスを指定します。プレースホルダーの Unsplash／ストック画像 URL があれば置き換えてください。
   • ランディングページのセクション → 関連するコンポーネント／JSX で新しいアセットをインポートまたは参照します。
   • OG 画像 → <meta property="og:image">／メタデータ設定を更新します。
   • README → 適切な Markdown 画像タグを追加します。

3. パス（相対パスと /static/... と @/assets/... の使い分け）、ファイル形式（png/webp/jpg）、ラッパーコンポーネント（next/image、カスタムの <Image> など）について、既存の慣例に合わせます。

4. 最初に質問しないでください。 ユーザーが用途の明確な画像を依頼した場合は、配置と組み込みを自動的に行い、最後に変更内容を伝えてください。保存先が本当に曖昧な場合に限り、質問してください。

エラー — 隠さずに伝える

次のいずれかが発生した場合は、直ちに停止してユーザーにエラーを報告してください。再試行したり、モデルを変更したり、プロンプトを変更したりしないでください。

• OPENAI_API_KEY is not set → キーの提供方法をユーザーに尋ねてください。
• openai package not installed → pip install --upgrade openai を実行するよう伝えてください。
• 403「organization must be verified」→ platform.openai.com/settings/organization/general で認証するよう伝えてください。 モデルを切り替えないでください。
• 400 サイズエラー → エラーを報告し、有効なサイズをユーザーに選んでもらってください。
• 透明な背景に関する 400 → エラーを報告してください。gpt-image-2 は透明度をサポートしていません。
• その他の API エラー → エラーをそのまま報告して停止してください。