openai-ads

OpenAI Ads キャンペーン

OpenAI Advertiser API を管理するための戦略ガイドです。すべての操作は https://api.ads.openai.com/v1 を通じて行います。

要件

• Hyper MCP がインストールされ、接続されていること。 https://app.hyperfx.ai/mcp
• OpenAI Ads インテグレーションが接続されていること（1 つの広告アカウントにスコープされた OpenAI Ads API キー）。https://app.hyperfx.ai/apps

search("openai_ads_ad_accounts_get") で openai_ads_ad_accounts_get が見つからない場合は、処理を中止し、Hyper MCP を有効にして OpenAI Ads を接続するようユーザーに伝えてください。接続後、openai_ads_health_check() でキーを検証します。connected=false の場合、API キーがないか、無効または期限切れです。

このスキルでツールを実行する方法

このスキルの各ツールは、正式なツール名で指定します。利用環境で提供されている呼び出し方法を使って実行してください。

環境	ツールを探す	実行する
MCP クライアント（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")、続けて describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"、続けて hyperai describe <name>	hyperai call <name> --json '{...}'

ツールが見つからない場合、そのインテグレーションは未接続か、ワークスペースで有効になっていません。処理を中止し、接続するインテグレーションをユーザーに伝えてください。

対象外 — 他のスキルに委ねる

• クリエイティブの生成（広告画像、コピー）→ ad-creative-generation / image-generation。
• 複数プラットフォームでのキャンペーン開始 → このスキルで OpenAI Ads を使用し、その後、別途 meta-ads / google-ads を呼び出してください。

重要なルール

重要：認証には OAuth ではなく、ベアラー API キーを使用します。1 つの Ads API キーは、ちょうど 1 つの広告アカウントにスコープされます。list ad accounts エンドポイントはありません。openai_ads_ad_accounts_get は、そのキーに接続されたアカウントを返します。

重要：入力する金額はすべて整数のマイクロ単位です。 $1.00 = 1_000_000 マイクロです。$50/day = 50_000_000 です。 daily_spend_limit_micros の最小値は 1_000_000（$1）です。広告グループの max_bid_micros の上限は 100_000_000（$100）です。インサイトのレスポンスでは、 マイクロ単位ではなく、アカウント通貨の通常の浮動小数点数が使われます。

重要：キャンペーン、広告グループ、広告は、必ず status="paused" で作成してください。作成した内容をユーザーに提示してから、承認後に専用の有効化エンドポイントを使って有効化します。

重要：広告には review_status があります。新しい広告は in_review となり、 status="active" であっても、review_status="approved" になるまでは配信されません。

重要：chat_card クリエイティブには target_url と file_id が必要です。 先に openai_ads_images_upload で画像をアップロードし、返された file_id を openai_ads_create に渡してください。PNG、1024x1024、1 MB 以下です。

重要：クリエイティブの種類は chat_card と product_ad_template です。 商品広告テンプレートは、選択した商品フィード項目から画像と遷移先 URL を取得するため、 file_id や target_url は必要ありません。

重要：キャンペーンの bidding_type には impressions または clicks を指定できます。 広告グループの billing_event_type には impression または click を指定できます。

ツールの概要

作業	ツール
アカウント	openai_ads_ad_accounts_get, openai_ads_update_ad_account, openai_ads_activate_ad_account, openai_ads_pause_ad_account, openai_ads_health_check
キャンペーン	openai_ads_campaigns_create, openai_ads_campaigns_get, openai_ads_campaigns_list, openai_ads_campaigns_update, openai_ads_campaigns_pause, openai_ads_campaigns_activate, openai_ads_campaigns_archive
広告グループ	openai_ads_ad_groups_create, openai_ads_ad_groups_get, openai_ads_ad_groups_list, openai_ads_ad_groups_update, openai_ads_ad_groups_pause, openai_ads_ad_groups_activate, openai_ads_ad_groups_archive
広告	openai_ads_create, openai_ads_get, openai_ads_list, openai_ads_update, openai_ads_pause, openai_ads_activate, openai_ads_archive
画像とターゲティング	openai_ads_images_upload, openai_ads_search_geo_locations
オーディエンス	openai_ads_create_custom_audience, openai_ads_create_custom_audience_upload, openai_ads_get_custom_audience, openai_ads_list_custom_audiences, openai_ads_archive_custom_audience
コンバージョン	openai_ads_create_conversion_pixel, openai_ads_create_conversion_api_key, openai_ads_create_conversion_event_setting, openai_ads_list_conversion_event_settings, openai_ads_get_conversion_insights
インサイト	openai_ads_account_insights_get, openai_ads_campaign_insights_get, openai_ads_ad_group_insights_get, openai_ads_insights_get
キャッシュスナップショット	openai_ads_cache, openai_ads_caches_get, openai_ads_caches_refresh

フェーズ 1：アカウントの確認

接続後に、次を実行します。

openai_ads_ad_accounts_get()
openai_ads_campaigns_list(limit=100)
openai_ads_list_custom_audiences(limit=100)
openai_ads_list_conversion_event_settings(limit=100)

接続時のコンテキストビルダーによって、キャッシュ済みスナップショットがすでに作成されている場合があります。 次を優先してください。

openai_ads_caches_get()

キャッシュが空で success=False となる場合は、一度更新します。

openai_ads_caches_refresh()

フェーズ 2：計画と確認

何かを作成する前に、次の内容をユーザーに確認します。

• 目的（平易な言葉で）。
• アカウント通貨での日予算および／または通算予算。
• ターゲット地域：["US", "GB"] のような単純な国コード、または openai_ads_search_geo_locations で取得したロケーション ID。
• 含める、または除外するカスタムオーディエンス。
• 通常の chat_card キャンペーンにするか、商品フィードキャンペーンにするか。
• chat_card の見出し（title、50 文字以下）、本文（100 文字以下）、クリック先 URL。
• chat_card 用の画像アセット 1 点（公開 URL または base64 blob）。
• マイクロ単位での最大入札額（max_bid_micros、例：2_000_000）。
• 任意の context_hints。広告を表示する状況を説明する、短い自然言語のフレーズです。
• キャンペーンに関連付ける任意のコンバージョンイベント設定 ID。

不足している情報があれば、質問してください。予算、地域、広告文を推測してはいけません。

すべてのリファレンスファイルは references/ にあります。 references/<file> から読み込んでください（例：references/campaign-creation.md）。

ルーティング表

ユーザーの要望	先に読むファイル
チャットカードまたは商品フィードキャンペーンを開始する	上記のフェーズ 1～2 → references/campaign-creation.md
地域／DMA／カスタム地域をターゲティングする	references/campaign-creation.md — 地域ターゲティング
カスタムオーディエンスを作成または管理する	references/audiences-and-conversions.md
コンバージョントラッキング（ピクセル、API キー、イベント設定）をセットアップする	references/audiences-and-conversions.md
レビュー後に有効化する	references/campaign-creation.md — 有効化
インサイトの取得／ステータスの管理／キャッシュスナップショットの更新	references/insights-and-operations.md

安全ルール

絶対に次のことをしないでください：

• 金額をドル単位で直接渡さないでください。金額の入力値はすべてマイクロ単位です。
• ユーザーの明示的な承認なしに、キャンペーン、広告グループ、広告、またはアカウントを有効化しないでください。
• chat_card の画像アップロードを省略しないでください。実際の file_id が必要です。
• 地域の除外を使用しないでください。代わりに対象地域を指定し、オーディエンスを除外してください。
• status="active" であることだけを理由に、広告が配信中だと判断しないでください。必ず review_status を確認してください。
• archive は取り消せないものとして扱ってください。
• 新しい広告への有料トラフィックを約束しないでください。新しい広告は、OpenAI の承認を受けるまで review_status="in_review" の状態になります。