chatgpt-image-ad

chatgpt-image-ad（Arcads）

Arcads の POST /v2/images/generate を model: "gpt-image-2" で呼び出し、単体で使える Meta 広告用画像クリエイティブを 1 点以上生成します。画像のパスは Meta-ad-builder スキルに引き渡します。このスキル自体は Meta にアップロードしません。

読む順序

1. このファイル — Arcads 固有のエンドポイント、認証、署名付きアップロードフロー、ワークフローの各フェーズ。
2. shared/skills/chatgpt-image-ad/prompting/guide.md — モデル固有のプロンプト作成方法（gpt-image-2 の得意・不得意なこと、nano-banana に切り替えるタイミング）。
3. shared/skills/image-ad-prompting/prompting/prompt-library.md — モデルごとの注記付き、検証済みテンプレート 30 種以上。
4. shared/skills/image-ad-prompting/prompting/safety-suffixes.md — 常時適用する 3 つのガード。
5. scripts/generate_image.py — ヘルパースクリプト（Python 標準ライブラリのみ）。

厳守事項 — 緩和しないでください

1. モデルは gpt-image-2 です。 スクリプトは他の値を拒否します。ユーザーから nano-banana を求められた場合は、nano-banana-image-ad を案内してください。
2. 出力にプラットフォーム／スクリーンショットのクロームを含めないでください。 NO_CHROME_SUFFIX は常に有効です（広告のコンセプトにクロームが必要な場合に限り、まれに --allow-chrome で上書きできます）。
3. --no-safe-zone が明示されていない限り、エッジセーフとグリフ安全性のサフィックスは常に有効にしてください。 実際に発生する問題を防ぐため、黙って削除しないでください。
4. 参照画像は最大 5 点です。 gpt-image-2 の Arcads における上限です（実際に 400 Max 5 reference image(s) allowed を確認済み）。スクリプトで制限されています。
5. このスキルから Meta にアップロードしないでください。 画像生成のみを行います。ユーザーは別途、スタック内に広告ビルダースキルを持っています。ファイルシステム上のパスを使って引き渡してください。
6. 生成前に、必ずクレジット費用の見積もりを提示してください（Arcads の arcads-external-api スキルの規約を参照）。gpt-image-2 の呼び出し 1 回につき画像 1 点が生成されます。--n のバリエーション数を掛けてください。

前提条件

• .env に ARCADS_BASIC_AUTH（推奨、エンコード済み）または ARCADS_API_KEY が設定されていること
• 任意：生成アセットを Arcads ダッシュボード内の適切なフォルダーに保存するため、.env に PRODUCT_ID、PROJECT_ID が設定されていること（セッションフォルダーパターンについては arcads-external-api の SKILL.md を参照）
• ローカルディスク上に参照画像があること（PNG/JPG/JPEG/WEBP/GIF）。Arcads の署名付きアップロードフローはスクリプト内で処理されるため、ローカルパスを渡します。

設定

• ベース URL： https://external-api.arcads.ai（または ARCADS_BASE_URL）。
• 認証： HTTP Basic。スクリプトは、エンコード済みの ARCADS_BASIC_AUTH 環境変数（例：Basic ZXhhbXBsZTo=）を優先します。設定されていない場合は、ARCADS_API_KEY を空のパスワードとともにエンコードします。
• エンドポイント： POST /v2/images/generate（リクエスト）；GET /v1/assets/{id}（status: generated になるまでポーリング）；ステータスが切り替わったら画像 URL を取得します。
• 参照画像のアップロード： POST /v1/file-upload/get-presigned-url が {presignedUrl, filePath} を返します。presignedUrl にバイトデータを PUT し、referenceImages に filePath 文字列を渡します。各 filePath は 1 回限りの使用です。並列実行時に競合しないよう、スクリプトはバリエーションごとに再アップロードします。

生成モード

モード	使用する場合	必須	任意
image（デフォルト）	新しい広告画像を生成します。	--prompt、--aspect-ratio	--image-ref（最大 5 点）
image_edit	既存の画像を変更します（色の置き換え、背景の変更、要素の追加）。	--prompt、--source	--image-ref（最大 5 点）

対応するアスペクト比

1:1、16:9、9:16。Arcads の /v2/images/generate エンドポイントで受け付けられるのは、この 3 種類のみです（実機で確認済み：aspectRatio must be one of the following values: 1:1, 16:9, 9:16）。共有ライブラリ内の 2:3、3:2、4:5 などを使うテンプレートは、このバックエンドでは本来の比率でレンダリングされません。1:1 に変更してトリミングするか、専用の /gpt4o-image/generate エンドポイント経由で 2:3 と 3:2 にネイティブ対応する KIE chatgpt-image-ad の姉妹スキルを使用してください。

ユーザーが指定する入力

入力	備考
シードプロンプト	ユーザーの言葉によるクリエイティブの方向性です。Phase 3 で書き換えます。
アスペクト比	上記 5 種類のいずれかです。それ以外は拒否します。
参照画像	任意ですが、広告に特定の製品が登場する場合は強く推奨します。最大 5 枚です。
バリアント数 N	デフォルトは 1 です。上限は 5 です。
モード	image（デフォルト）または image_edit です。
ソース画像	image_edit の場合のみ必須です。

ワークフロー

Phase 1: 事前確認

1. .env に ARCADS_BASIC_AUTH または ARCADS_API_KEY が設定されていることを確認します。
2. （任意）arcads-external-api のセッションフォルダーを設定します（そのスキルの「Session setup」セクションを参照）。PRODUCT_ID / PROJECT_ID が設定されていない場合、生成されたアセットはデフォルトのプロジェクトに配置されます。後から POST /v1/assets/add-to-project で修正できます。
3. ヘルスチェックを実行します。curl -sf -H "$AUTH" "$BASE_URL/v1/products" が 200 を返すことを確認します。

Phase 2: 入力の収集

シードプロンプト、モード、ソース（編集する場合）、参照画像のパス、バリアント数、アスペクト比を収集します。

Phase 3: プロンプトの書き換え

shared/skills/image-ad-prompting/prompting/prompt-library.md を読みます。ユーザーのブリーフがテンプレートに当てはまる場合は、Model notes ブロックを確認し、gpt-image-2 が clean または preferred と記されている場合にのみ続行します。nano-banana が preferred の場合は、生成前にスキルの切り替えを提案します。

{placeholders} を埋め、書き換えたプロンプトをユーザーに提示します。「これを使いますか、編集しますか、それとも最初からやり直しますか？」と尋ねます。承認されるまで繰り返します。

新規プロンプト（テンプレートに当てはまらない場合）は、shared/skills/chatgpt-image-ad/prompting/guide.md § Phase 3b の構成に従います。

Phase 4: クレジット費用の確認（必須）

arcads-external-api の規約に従い、推定クレジット費用を提示します（過去の該当する呼び出しについては logs/arcads-api.jsonl から、または料金表については MASTER_CONTEXT.md から読み取ります）。実行前に明示的な確認を待ちます。

Phase 5: 生成

~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py \
  --prompt "<rewritten>" \
  --aspect-ratio <ratio> \
  --n <N> \
  --image-ref <product.png> \
  [--image-ref <style-board.png>] \
  --out ./generated \
  --env-file .env

# For an edit run:
~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py \
  --mode image_edit \
  --prompt "<edit-instruction>" \
  --source <existing.png> \
  [--image-ref <guidance.png>] \
  --n <N> \
  --out ./generated \
  --env-file .env

標準出力の各行は、1 つの JSON バリアントです（variant、path、asset_id、width、height、prompt、mode、aspect_ratio、model）。

arcads-external-api スキルの規約に従い、各呼び出しを logs/arcads-api.jsonl に記録します。model=gpt-image-2、バリアント数、referenceImages の数、返された asset_id を記録します。

Phase 6: ビジュアル QA（必須）

完了した各バリアントについて、画像を読み込んで次の点を確認します。

• 判読不能な小さな文字（本文の文字量が多い場合に最もよく発生する gpt-image-2 の失敗）
• ワードマークのずれ（ブランドのワードマークが --image-ref として渡されていない場合）
• 文字数の誤り（例：Slack メッセージが 3 件ではなく 4 件）
• iOS ダイアログ／UI の比率のずれ

不具合がある場合は、問題を明示的に修正するプロンプトに改訂して再生成します（shared/skills/chatgpt-image-ad/prompting/guide.md § Retry mode を参照）。各バリアントにつき、再試行は最大 2 回です。

Phase 7: 確認と引き継ぎ

すべてのパスをユーザーに提示します。「すべて使う／指定したものを使う／再生成する／キャンセルする」と尋ねます。

選択されたバリアントは、Meta-ad-builder スキル（複製、コピー、アップロードを扱う別のスキル）で使用できる状態です。ユーザーがパイプで渡せるよう、パスを出力します。

必要に応じて、選択したパスを ./generated/run-<ts>.jsonl に書き込みます（1 行につき 1 つのパスを JSON 形式でラップします）。これは後続処理で使用できます。

対象外 — 明確に失敗として扱う

• Meta へのアップロード — スタック内の別のスキルを使用します。
• Nano Banana / Gemini による画像生成 — nano-banana-image-ad を使用します。
• 動画、カルーセル、DCO 広告 — 画像のみが対象です。
• 広告コピーの作成 — 別のスキルを使用します。
• 共有プロンプトライブラリーの編集 — image-ad-clone を使用します（Phase 1 でバックエンドを尋ねます）。

よくあるエラー

• 401/403 → arcads-external-api のセットアップ手順に従って .env を修正してください。
• 400 Max 5 reference image(s) allowed → --image-ref の数を5以下に減らしてください。
• 422 validation/moderation → プロンプトをより明確にしてください。aspectRatio がサポート対象に含まれていることを確認してください。
• 500 UNKNOWN_ERROR → 通常、古い署名付きの filePath を再利用したことが原因です。スクリプトはバリエーションごとに再アップロードします。それでもこのエラーが表示される場合は、レスポンスに含まれる asset_id を添えてイシューを報告してください。

このスキルが管理するファイル

• ~/.claude/skills/chatgpt-image-ad/SKILL.md — このファイル
• ~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py — Arcads の gpt-image-2 呼び出し（署名付きアップロード＋生成＋ポーリング＋ダウンロード）

関連項目

• shared/skills/chatgpt-image-ad/prompting/guide.md — モデル固有のプロンプト作成（gpt-image-2 の強みと制限、nano-banana に切り替えるタイミング）
• shared/skills/image-ad-prompting/prompting/prompt-library.md — 共通テンプレートライブラリ（モデルごとの注記付きで30件以上）
• shared/skills/image-ad-prompting/prompting/template-format.md — 新しいテンプレート用のエントリーひな形
• shared/skills/image-ad-prompting/prompting/safety-suffixes.md — 常時有効な3つのガード
• image-ad-clone スキル — 既存の広告をリバースエンジニアリングし、再利用可能なライブラリエントリーにする、バックエンドに依存しない単一のスキル
• arcads-external-api スキル — Arcads の基盤となる規約（セッションフォルダー、クレジットコスト、QA ループ、ログ）
• nano-banana-image-ad スキル — 写実的な画像、ライフスタイル画像、複数の参照画像を使うテンプレート向けの関連スキル