snapchat-ads

Snapchat Ads 广告系列

通过 Snapchat Marketing API v1 管理 Snapchat 广告的策略指南。此工具包是原始 HTTP 客户端，因此必须严格按照文档发送参数类型——字符串用字符串，整数用整数，所有金额均以微货币为单位。

要求

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

如果 search("snapchat_ads_list_organizations") 未找到 snapchat_ads_list_organizations，请停止并告知用户启用 Hyper MCP 并连接 Snapchat 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 '{...}'

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

不在本指南范围内——请交由其他技能处理

• 创意素材生成（广告文案、图片、视频）→ ad-creative-generation / video-generation。
• 跨平台广告系列启动 → Snapchat 请使用此技能，然后分别调用 meta-ads / tiktok-ads。

关键规则

关键：所有预算和出价均以微货币为单位。$1.00 = 1,000,000 微单位。$50/天 = 50000000。切勿直接传入美元金额。广告系列的最低每日预算 / 总支出上限为 $20（20000000）。

关键：创建广告系列、广告组和广告时，设置 status="PAUSED"。未经用户明确审核，切勿启动投放。由于所有内容默认都处于 PAUSED 状态，你可以构建完整的广告系列后将其删除，且不会产生费用——非常适合演示。

关键：更新采用 JSON-Patch 部分更新——只传入要更改的字段，并指定其父级实体。snapchat_ads_update_campaign 需要 ad_account_id；snapchat_ads_update_ad_squad 需要 campaign_id（不是 ad_account_id）；snapchat_ads_update_ad 需要 ad_squad_id。

关键：账户级统计数据（entity_type="adaccounts"）仅支持 fields="spend"。若要查询展示次数 / 滑动次数 / 转化次数，请查询广告系列、广告组、广告、创意或媒体级别的数据。

关键：不存在 time_range 预设（例如，LAST_30_DAYS 并不存在）。请传入 start_time 和 end_time（ISO 8601 格式）。两者均省略时，返回的是全时段汇总数据，而非近期时间范围的数据。

关键：广告组的 billing_event 始终为 IMPRESSION。当 bid_strategy="LOWEST_COST_WITH_MAX_BID" 或 "TARGET_COST" 时，必须提供 bid_micro；当 bid_strategy="AUTO_BID" 时，请省略此参数。

重要：创建广告组需要广告账户中有有效的资金来源。如果账户处于 PENDING 状态 / 没有资金，广告组创建会失败——这是账单状态问题，并非程序错误。

重要：创意需要 top_snap_media_id（已上传的媒体 ID）和 headline（≤ 34 个字符）。brand_name 不得超过 32 个字符。

重要：对于 LOWEST_COST_WITH_MAX_BID / TARGET_COST，不要猜测 bid_micro——请使用 snapchat_ads_get_bid_estimate 获取 Snapchat 建议的范围（构建前按定向规范查询，或构建后按 ad_squad_id 查询）。创建任何内容前，也请使用 snapchat_ads_get_audience_size 估算受众规模。

重要（客户名单）：snapchat_ads_add_segment_users 要求标识符已完成规范化和 SHA-256 哈希处理（电子邮件在哈希前去除首尾空格并转换为小写；电话号码只保留数字并包含国家代码；移动广告 ID 转换为小写并保留连字符）。每次调用只能使用一种架构类型（EMAIL_SHA256、PHONE_SHA256、MOBILE_AD_ID_SHA256），最多 100,000 个 ID。切勿发送原始个人身份信息（PII）。匹配为异步处理——处理完成后才会更新细分受众规模。

工具范围

分组	工具
组织与账户	snapchat_ads_list_organizations、snapchat_ads_list_ad_accounts、snapchat_ads_get_ad_account
广告系列	snapchat_ads_list_campaigns、snapchat_ads_get_campaign、snapchat_ads_create_campaign、snapchat_ads_update_campaign、snapchat_ads_delete_campaign
广告组	snapchat_ads_list_ad_squads、snapchat_ads_get_ad_squad、snapchat_ads_create_ad_squad、snapchat_ads_update_ad_squad、snapchat_ads_delete_ad_squad、snapchat_ads_estimate_ad_squad_outcomes
广告	snapchat_ads_list_ads、snapchat_ads_get_ad、snapchat_ads_create_ad、snapchat_ads_update_ad、snapchat_ads_delete_ad
创意素材	snapchat_ads_list_creatives、snapchat_ads_get_creative、snapchat_ads_create_creative
媒体	snapchat_ads_list_media、snapchat_ads_create_media、snapchat_ads_upload_media
报告	snapchat_ads_get_stats、snapchat_ads_create_stats_report、snapchat_ads_get_stats_report
转化	snapchat_ads_list_pixels、snapchat_ads_list_custom_conversions
受众	snapchat_ads_list_segments、snapchat_ads_get_segment、snapchat_ads_create_segment、snapchat_ads_update_segment、snapchat_ads_delete_segment、snapchat_ads_add_segment_users、snapchat_ads_remove_segment_users
规划预估	snapchat_ads_get_audience_size、snapchat_ads_get_bid_estimate、snapchat_ads_get_audience_insights
定向	snapchat_ads_search_targeting

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

路由表

用户想要……	首先阅读这些文件
投放 Snapchat 广告系列	references/discovery.md → references/campaign-creation.md
上传媒体／创建创意素材／广告组／广告	references/campaign-creation.md
确定定向条件（地理位置、人口统计、兴趣、设备）	references/targeting.md
构建自定义受众／相似受众／受众洞察	references/targeting.md
预估受众规模／获取建议出价	references/campaign-creation.md
设置 Snap Pixel／自定义转化	references/conversions-and-reporting.md
获取统计数据／异步报告／更新或删除实体	references/conversions-and-reporting.md
目标尚不明确	references/discovery.md — 通过需求探索明确目标

广告系列工作流

发现组织／账户 → 审查账户 → 调研（目标、受众、预算、素材）→ 确认策略 → 创建广告系列（PAUSED）→ 上传媒体 → 创建创意素材 → 创建广告组 → 创建广告 → 与用户审核 → 启用（使用 update_* 将状态设为 ACTIVE）。

已知限制

问题	解决方法
创建创意失败（过去会静默返回 null 错误）	几乎总是缺少 profile_properties.profile_id（所有创意类型都必需）——从 list_creatives 获取一个。现在工具会抛出明确错误，而不是返回 null 的“成功”。
创建广告时类型不匹配	省略 type，让系统根据创意推导类型（WEB_VIEW → REMOTE_WEBPAGE 等）。
预测返回 OE101 / UNSUPPORTED_DELIVERY_CONSTRAINT	工具会自动添加 delivery_constraint；如果问题仍然存在，则表示该账户类型（通常是 PARTNER）无法进行效果估算——请使用 Ads Manager 的覆盖人数规划工具。
DAY 粒度的统计数据拒绝该时间范围（E1008）	已自动处理——将 ad_account_id 传给 get_stats/create_stats_report，工具会将时间调整到账户时区的午夜和整点边界。
媒体因 E2601（“无法用于创建任何创意类型”）被拒绝	文件不符合规格——请使用 1080×1920（9:16）、≤ 5 MB 的 PNG/JPG 图片，或 1080×1920 的 MP4/MOV。按正确尺寸重新生成素材、重新上传，并确认 media_status 为 READY。
从 file_path / 内部 URL 上传失败（Errno 2 / DNS 错误）	改为传入 file_id（Hyper 文件 ID）——工具会直接从存储中读取。避免使用服务器本地路径和内部 files.* URL。
账户级统计数据拒绝非 spend 字段（错误 E1008）	在 campaign/adsquad/ad/creative/media 级别查询其他指标。
未提供 time_range/日期预设	传入 start_time + end_time；省略它们会返回生命周期总计。
未注资的账户创建广告组失败	添加资金来源；没有资金来源也可以使用 campaigns/media/creatives。
非 AUTO_BID 策略要求提供 bid_micro	使用 LOWEST_COST_WITH_MAX_BID / TARGET_COST 时，请提供 bid_micro。
媒体 > 32 MB	已自动处理（分块上传，最大 1 GB）。
部分更新	使用更新工具（PATCH）并传入正确的父级 ID——切勿重新发送整个对象。
客户名单上传“成功”，但细分群体仍然很小	上传前必须先规范化标识符并进行 SHA-256 哈希；匹配是异步的，只有与 Snapchat 用户匹配的哈希才会计入。处理完成后，请检查细分群体的 approximate_number_users。
类似受众创建被拒绝	类似受众需要健康的种子：包含足够匹配用户的 FIRST_PARTY 细分群体、countries（ISO-2）以及 ≤ 180 的 retention_in_days。

安全规则

切勿：

• 假定组织、广告账户、campaign、媒体或创意 ID——请查询或询问。
• 跳过账户审计阶段。
• 未经用户明确批准就创建 campaigns、广告组或广告。
• 未经用户同意就将任何内容设为 ACTIVE。
• 传入美元金额，而不是微货币。
• 在 adaccounts 级别查询非 spend 指标。
• 使用 time_range 预设——始终传入 start_time/end_time。
• 使用 LOWEST_COST_WITH_MAX_BID / TARGET_COST 却不提供 bid_micro。
• 向更新工具传入错误的父级 ID（广告组 → campaign_id，广告 → ad_squad_id）。