pinterest-ads

Pinterest Ads

用于通过 Hyper MCP 暴露的 Pinterest Ads API v5 接口管理 Pinterest Ads 广告系列的战略技能。创建广告组时会直接调用 REST（绕过 SDK 模型转换），因此必须严格按照文档发送参数类型——字符串用字符串，整数用整数。

不在本技能范围内 — 请转交给其他技能

请求	转交给
Google Ads 广告系列	google-ads
Meta（Facebook / Instagram）广告系列	meta-ads
Amazon Sponsored Products	amazon-ads
TikTok 广告系列	tiktok-ads
在 Meta Ads Library 中研究竞争对手广告	meta-ads-library
Pinterest 自然 Pin 发布	当前未提供 — 请使用 Pinterest 应用

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已连接 Pinterest Ads 集成，地址为 https://app.hyperfx.ai/apps（拥有广告账户访问权限的 Pinterest Business 账户）。

如果 search("pinterest_ads_ad_accounts_list") 找不到 pinterest_ads_ad_accounts_list，请停止并告知用户启用 Hyper MCP 并连接 Pinterest Ads。

如何运行此技能中的工具

此技能中的每个工具都使用其规范工具名称。请使用当前界面提供的调用方式运行：

界面	查找工具	运行工具
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 '{...}'

如果找不到某个工具，说明其集成尚未连接或未在工作区启用：请停止并告知用户需要连接哪个集成。

工具接口

工具组	工具
账户	pinterest_ads_ad_accounts_list、pinterest_ads_ad_accounts_get
广告系列	pinterest_ads_campaigns_list、pinterest_ads_campaigns_get、pinterest_ads_campaigns_create、pinterest_ads_campaigns_update
广告组	pinterest_ads_ad_groups_list、pinterest_ads_ad_groups_get、pinterest_ads_ad_groups_create、pinterest_ads_ad_groups_update
广告	pinterest_ads_list、pinterest_ads_get、pinterest_ads_create、pinterest_ads_update
受众	pinterest_ads_audiences_list、pinterest_ads_audiences_create、pinterest_ads_customer_lists_create
转化	pinterest_ads_conversion_tags_list、pinterest_ads_conversion_tags_create、pinterest_ads_conversion_events_send
关键词	pinterest_ads_keywords_create
分析	pinterest_ads_campaign_analytics_get

关键规则

关键：所有预算和出价的单位都是微货币。$1.00 = 1,000,000 微美元。$50/天 = 50,000,000。切勿直接传入美元金额。

关键：使用 is_flexible_daily_budgets: true 时，还必须设置 is_campaign_budget_optimization: true。FDB 需要 CBO。

关键：终身预算 CBO 广告系列必须包含 end_time（Unix 时间戳）。

关键：创建广告系列时，初始状态必须为 PAUSED。未经用户审核，切勿直接投放。

关键：WEB_CONVERSION 广告组必须使用 billable_event="IMPRESSION"（不能使用 CLICKTHROUGH），并且必须包含带有 attribution_windows、conversion_event、conversion_tag_id 和 cpa_goal_value_in_micro_currency 的 optimization_goal_metadata。

关键：创建关键词时必须提供 match_type。如果缺少该参数，API 会返回 500 错误。

关键：CBO 广告系列在广告系列层级管理预算。对于 CBO 广告系列下的广告组，切勿设置 budget_in_micro_currency。

重要：对于 ENGAGEMENT 受众，retention_days 已弃用。请勿在受众规则中包含该参数。

核心流程

发现 → 审核账户 → 调研（目标、受众、素材）→ 确认策略 → 创建广告系列（PAUSED）→ 创建广告组 → 创建广告 → 审核 → 仅在获得用户批准后启用。

所有参考文件都位于 references/ 中。 在 references/<file> 处读取（例如 references/discovery.md）。

路由表

用户想要……	首先读取这些文件
创建广告系列（任何目标）	references/discovery.md → references/campaigns.md
创建 WEB_CONVERSION 广告系列	references/discovery.md → references/campaigns.md（严格使用 WEB_CONVERSION 模板）+ references/audiences-and-conversions.md（用于转化标签）
创建或管理受众／客户名单	references/audiences-and-conversions.md
设置转化跟踪／发送转化事件	references/audiences-and-conversions.md
向广告组添加关键词	references/keywords-and-analytics.md
获取广告系列分析数据	references/keywords-and-analytics.md
更新或暂停现有广告系列／广告组／广告	references/keywords-and-analytics.md
尚不明确目标	references/discovery.md — 通过调研明确目标

已知限制

问题	解决方法
创建关键词时未提供 match_type 会返回 500	始终指定 match_type（BROAD、PHRASE、EXACT）。
retention_days 对 ENGAGEMENT 受众已弃用	从规则字典中省略。
WEB_CONVERSION 广告组需要许多参数	严格使用 WEB_CONVERSION 模板 — 包含完整的 optimization_goal_metadata。
WEB_CONVERSION 广告组必须使用 IMPRESSION billable_event	WEB_CONVERSION 不得使用 CLICKTHROUGH。
CBO 广告系列不接受广告组预算	父广告系列启用 CBO 时，不得设置 budget_in_micro_currency。
cpa_goal_value_in_micro_currency 必须是字符串	传入 "5000000"，而不是 5000000。
conversion_tag_id 必须是账户中的真实标签	先列出转化标签，再使用现有标签 ID。

安全规则

切勿：

• 假定 Pin ID 或广告账户 ID — 始终询问或查询。
• 跳过账户审核阶段。
• 未经明确批准就创建广告系列。
• 未经用户同意就将广告系列设为 ACTIVE。
• 传入美元金额，而不是微货币金额。
• 对 ENGAGEMENT 受众使用 retention_days。
• 创建 WEB_CONVERSION 广告组时不提供 optimization_goal_metadata。
• 对 WEB_CONVERSION 广告系列使用 CLICKTHROUGH billable_event（请使用 IMPRESSION）。
• 为 CBO 广告系列设置广告组预算。
• 创建关键词时不指定 match_type。
• 将 cpa_goal_value_in_micro_currency 作为整数传入（必须是类似 "5000000" 的字符串）。
• 在 WEB_CONVERSION 优化元数据中省略 conversion_tag_id（先列出标签，并使用真实 ID）。