openai-ads

OpenAI Ads 广告系列

OpenAI Advertiser API 管理策略指南。所有操作均通过 https://api.ads.openai.com/v1 进行。

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已连接 OpenAI Ads 集成（一个限定于单个广告账户的 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。

重要规则

至关重要：身份验证使用 Bearer API 密钥，而非 OAuth。一个 Ads API 密钥严格限定于一个广告账户。没有 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，在 review_status="approved" 之前不会投放，即使 status="active" 也不例外。

至关重要：chat_card 创意素材需要 target_url 和 file_id。 先通过 openai_ads_images_upload 上传图像，然后将返回的 file_id 传给 openai_ads_create。图像须为 PNG 格式、尺寸为 1024x1024，且不超过 1 MB。

重要：创意素材类型为 chat_card 和 product_ad_template。 产品广告模板会从选定的商品 Feed 项目中获取图像和目标网址，因此不需要 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 广告系列，还是商品 Feed 广告系列。
• chat_card 的标题（title，不超过 50 个字符）、正文（不超过 100 个字符）和点击跳转 URL。
• chat_card 的一个图片素材，可以是公开 URL 或 base64 数据块。
• 最高出价（以微单位计，max_bid_micros；例如 2_000_000）。
• 可选的 context_hints，用于描述广告应在何时展示的简短自然语言短语。
• 可选的、要关联到广告系列的转化事件设置 ID。

如果有任何信息缺失，请询问。不要自行编造预算、地理位置或广告文案。

所有参考文件都位于 references/ 中。 请读取 references/<file> 中的文件（例如 references/campaign-creation.md）。

路由表

用户想要……	请先阅读这些文件
启动聊天卡片或商品 Feed 广告系列	上述阶段 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 视为可逆操作。
• 承诺新广告会获得付费流量。新广告会一直处于 review_status="in_review"，直到 OpenAI 批准。