reddit-ads

Reddit Ads 广告系列

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

要求

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

如果通过 search 找不到 reddit_ads_get_me / reddit_ads_list_businesses，请停止并告知用户启用 Hyper MCP 并连接 Reddit 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 '{...}'

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

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

• Reddit 自然内容研究（挖掘 subreddit 讨论、痛点和客户之声）→ customer-research。
• 创意生成（广告文案、图片）→ ad-creative-generation。
• 跨平台广告系列启动 → 使用此技能处理 Reddit，然后分别调用 meta-ads / google-ads / tiktok-ads。

关键规则

重要：所有预算和出价均以微货币表示。$1.00 = 1,000,000 微单位。$50/天的预算应设置为 goal_value=50000000；$0.50 的 CPC 应设置为 bid_value=500000。切勿直接传入美元金额。

重要：创建广告系列、广告组和广告时，设置 configured_status="PAUSED"（工具包的默认值）。未经用户明确审核，切勿启动投放。由于所有内容默认均为 PAUSED，你可以构建完整的广告系列并将其归档，而不会产生费用——非常适合演示。

重要：发现流程通过商业账户进行，而不是通过平铺的账户列表：reddit_ads_get_me → reddit_ads_list_businesses → reddit_ads_list_ad_accounts(business_id=...)。不存在顶层的“列出所有广告账户”调用。

重要：广告推广的是帖子——需要 post_id（或 profile_id 加创建操作），而不是原始创意字段。创建广告前，先查找现有帖子（reddit_ads_list_posts）或创建帖子（reddit_ads_create_post）。API 只能推广社区帖子。

重要：广告组的 targeting.communities 数组接受的是subreddit 名称，而非 search_targeting 返回的 t5_ ID。请使用搜索结果中的 name 字段："communities": ["marketing", "SaaS", "Entrepreneur"]——传入 t5_... ID 会导致“You cannot set invalid communities”错误。（interests 使用 ID；geolocations 使用 "US" 这样的国家/地区代码。）

重要：构建广告组之前，必须先用 reddit_ads_search_targeting 解析定向选项——切勿猜测取值。targeting 是 create_ad_group 的命名参数；其他易变字段（受众、排期）则通过 input_data 传入。

重要：创建广告组时，必须提供 start_time（ISO 8601）。对于广告系列，仅在启用 CBO 时才能设置 start_time——对于非 CBO 广告系列，请省略广告系列级别的该参数，并在广告组级别设置，否则会出现“Cannot set start_time for a campaign without having campaign budget optimization enabled.”错误。 关键：对于 CPC/CPM/CPV/CPV6，bid_type 始终要求提供 bid_value，即使 bid_strategy="MAXIMIZE_VOLUME" 也是如此。设置一个上限（例如，bid_value=600000 = $0.60），或通过 reddit_ads_generate_bid_suggestion 获取建议值。

关键：无法立即硬删除。Reddit 要求实体先归档至少 3 小时，才能永久删除。reddit_ads_delete_* 会尝试执行真正的删除；如果实体尚不可删除，则会退而执行归档（这会停止投放）。请检查返回的 configured_status（ARCHIVED 或 DELETED），并告知用户，归档约 3 小时后即可硬删除。

关键：报告（reddit_ads_get_report）要求提供 fields、starts_at 和 ends_at。支出指标以微货币为单位返回。

重要：广告系列要求提供 name、objective，并且（若要投放）提供 funding_instrument_id——使用 reddit_ads_list_funding_instruments 列出可用项。以转化为优化目标的广告组需要提供 conversion_pixel_id（使用 reddit_ads_list_pixels）。从 2026-07-13 起，广告组和 CBO 广告系列都要求提供 conversion_pixel_id。

重要：潜在客户开发可用作广告系列的目标（LEAD_GENERATION），但此工具包不支持管理潜在客户开发表单（需要受功能门控的权限范围）——请在 Reddit Ads Manager 中创建潜在客户开发表单。

关键（CONVERSIONS 广告系列）：广告组的 optimization_goal 必填；对于标准（非 CBO）CONVERSIONS 广告系列，唯一接受的值是 CLICKS。SIGN_UP、PAGE_VISIT、PURCHASE 等是有效的枚举值，但此广告系列类型不接受这些值（“Conversion goal ... is not valid for Conversions Campaigns”）。Reddit 分两层进行校验——先检查是否属于枚举值，再检查广告系列类型是否允许。请使用 optimization_goal="CLICKS"；投放仍由 CONVERSIONS 目标决定。

关键（帖子类型）：有效的帖子 type 值为 IMAGE、VIDEO、CAROUSEL、TEXT——不是 LINK。**TEXT 帖子属于“自由格式广告”：不能包含 click_url，也不能用于 CONVERSIONS 广告系列的广告。**对于任何带有目标链接的广告（尤其是 CONVERSIONS 广告），请推广 IMAGE / VIDEO / CAROUSEL 帖子。

关键（使用新媒体创建帖子）：优先使用 reddit_ads_create_structured_post——它接受一个 URL，由 Reddit 下载并托管，因此无需预先上传素材。创建过程是一个异步任务：该工具会轮询至 wait_seconds（默认 45）后返回任务；如果 status="SUCCESS"，则使用 job.post_id 作为广告的 post_id，否则请轮询 reddit_ads_get_structured_post_job。IMAGE 需要 media_url + destination_url；VIDEO 还需要 thumbnail_url；CAROUSEL 接受 1–6 个 {image_url, destination_url, ...} 卡片；PROMOTED_POST 会按 ID 推广现有的 SFW 社区帖子。call_to_action 是显示标签（"Sign Up"、"Learn More"），不能使用 "SIGN_UP"。旧版 reddit_ads_create_post 无法通过 URL 获取媒体——其 content[].media_url 必须引用已上传的 Reddit 素材（reddit_ads_list_creative_assets）；CTA 必须放在 content[] 内，且 TEXT 帖子的 content[] 必须为空。仅在复用现有素材时使用旧版工具。

重要：帖子创建后不可修改，评论除外——若要更改标题、媒体或目标链接，请创建新的结构化帖子。reddit_ads_update_post(post_id=..., allow_comments=...) 仅可切换评论（结构化帖子请设置 is_structured_post=True）。

工具概览

分组	工具
身份与发现	reddit_ads_get_me、reddit_ads_list_businesses、reddit_ads_list_ad_accounts、reddit_ads_get_ad_account、reddit_ads_list_funding_instruments
广告系列	reddit_ads_list_campaigns、reddit_ads_get_campaign、reddit_ads_create_campaign、reddit_ads_update_campaign、reddit_ads_delete_campaign
广告组	reddit_ads_list_ad_groups、reddit_ads_get_ad_group、reddit_ads_create_ad_group、reddit_ads_update_ad_group、reddit_ads_delete_ad_group
广告	reddit_ads_list_ads、reddit_ads_get_ad、reddit_ads_create_ad、reddit_ads_update_ad、reddit_ads_delete_ad
帖子与创意素材	reddit_ads_list_profiles、reddit_ads_get_profile、reddit_ads_list_posts、reddit_ads_create_post、reddit_ads_get_post、reddit_ads_update_post、reddit_ads_list_creative_assets、reddit_ads_get_creative_asset
结构化帖子（媒体通过 URL 提供）	reddit_ads_create_structured_post、reddit_ads_get_structured_post_job、reddit_ads_list_structured_posts、reddit_ads_get_structured_post
定向	reddit_ads_search_targeting、reddit_ads_suggest_keywords、reddit_ads_validate_keywords、reddit_ads_validate_geolocations
受众	reddit_ads_list_custom_audiences、reddit_ads_create_custom_audience、reddit_ads_get_custom_audience、reddit_ads_delete_custom_audience、reddit_ads_update_custom_audience_users、reddit_ads_list_saved_audiences、reddit_ads_create_saved_audience、reddit_ads_get_saved_audience、reddit_ads_update_saved_audience
像素与转化 API	reddit_ads_list_pixels、reddit_ads_list_pixels_by_business、reddit_ads_post_conversion_events、reddit_ads_get_pixel_last_fired_at
预测与访问权限	reddit_ads_generate_bid_suggestion、reddit_ads_get_reach_forecast、reddit_ads_get_feature_access
应用 / SKAdNetwork	reddit_ads_list_apps、reddit_ads_get_skan_availability、reddit_ads_get_app_last_fired_at_report
报告与历史记录	reddit_ads_get_report、reddit_ads_get_account_history

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

路由表

用户想要……	优先阅读这些文件
发起 Reddit 广告系列（任何目标）	references/discovery.md → references/campaign-creation.md
推广帖子 / 创建帖子（包括通过 URL 提供媒体）	references/campaign-creation.md
在发起前预测覆盖范围	references/discovery.md
管理自定义或已保存的受众 / 解决定向问题	references/audiences-and-targeting.md
设置像素 / 转化 API 跟踪	references/conversions-and-reporting.md
获取报告 / 更新或删除实体	references/conversions-and-reporting.md
尚不清楚目标	references/discovery.md — 通过发现流程明确目标

广告系列工作流

发现业务/账户 → 审查账户 → 调研（目标、定向、预算、帖子）→ 解析定向 ID → 确认策略 → 创建广告系列（PAUSED）→ 创建广告组 → 查找/创建帖子 → 创建广告 → 与用户审核 → 激活（通过 update_* 更新为 ACTIVE）。

已知限制

问题	解决方法
无法立即彻底删除；“必须先归档广告系列才能删除”／“归档后三小时内无法删除”	这是预期行为——delete_* 会自动归档（停止投放）；归档约 3 小时后才能彻底删除。稍后重新运行删除操作即可永久移除。
创建广告需要 post_id	推广现有社区帖子（list_posts），或创建一个帖子（create_post）；只能通过 API 推广社区帖子。
转化广告组因缺少像素而被拒绝	设置 conversion_pixel_id（从 list_pixels 获取）。从 2026-07-13 起，广告组／CBO 必须设置此项。
广告系列无法投放	添加 funding_instrument_id（从 list_funding_instruments 获取）；账户必须有资金。
无法通过 API 创建潜在客户开发表单	在 Reddit Ads Manager 中创建表单；API 只能设置 LEAD_GENERATION 目标。
创建变体时，定向、排期和创意字段不是命名参数	通过 input_data（一个字典）传入，这些数据会合并到请求正文中。
没有扁平的广告账户列表	按 get_me → list_businesses → list_ad_accounts(business_id) 的顺序查找。
"You cannot set invalid communities: {t5_...}"	targeting.communities 数组需要的是 subreddit 名称，而不是 search_targeting 返回的 t5_ ID。请使用 name 字段。
"Cannot set start_time ... without ... campaign budget optimization"	广告系列级别的 start_time 仅适用于 CBO。非 CBO 广告系列请省略此项；在广告组上设置 start_time。
创建广告组时，start_time 报错 "Input should be a valid datetime"	广告组必须设置 start_time——务必传入此项。
即使使用 MAXIMIZE_VOLUME，仍要求提供 bid_value	CPC/CPM/CPV/CPV6 始终需要 bid_value。请提供上限，或使用 generate_bid_suggestion。
generate_bid_suggestion："Additional fields not permitted"／"'start_time' is a required property"	duration 是 ISO 开始／结束时间范围（{"start_time": ..., "end_time": ...}），不是 {"days": N}。
创建时出现 Varnish 503	这是 Reddit 后端的暂时性错误。重试前，请先确认未创建重复项（list_campaigns）。
创建后 effective_status 显示 PENDING_APPROVAL	即使是 PAUSED 实体也属正常现象（广告审核）——状态会自动清除；这不代表失败。
CONVERSIONS 广告组："Conversion goal (optimization goal) is required"／"... is not valid for Conversions Campaigns"	必须设置 optimization_goal；对于非 CBO 的 CONVERSIONS，该值必须为 CLICKS（此广告系列类型不接受 SIGN_UP/PAGE_VISIT/PURCHASE）。
"'LINK' is not one of [CAROUSEL, IMAGE, TEXT, VIDEO]"	帖子的 type 必须是 IMAGE/VIDEO/CAROUSEL/TEXT；没有 LINK 类型。
创建广告："Posts used for ads in Conversion campaigns cannot be free-form ad"／"Free form ads cannot have a click url"	TEXT 帖子属于自由格式广告——CONVERSIONS 广告请使用 IMAGE/VIDEO/CAROUSEL。
IMAGE 帖子："Image is required"	使用旧版 create_post 时，请将素材放入 content[].media_url（从 list_creative_assets 获取的、已上传到 Reddit 的素材）；仅提供 post_url 不够。若要从新的媒体 URL 创建，请改用 reddit_ads_create_structured_post。
结构化帖子任务尚未完成（status 为 QUEUED／PROCESSING）	创建过程是异步的；创建工具会轮询至 wait_seconds（默认 45 秒）。如果仍在处理中，请轮询 reddit_ads_get_structured_post_job(post_creation_job_id=...)，直到状态为 SUCCESS（然后使用 post_id）或 CLIENT_ERROR／SERVER_ERROR（查看 error_message）。
需要更改帖子的标题／媒体／目标位置	无法更改——帖子不可修改。请创建新的结构化帖子。reddit_ads_update_post 只能切换 allow_comments。
帖子：call_to_action "Additional fields not permitted"	call_to_action 属于 content[] 内部，而非顶层字段；并且应使用显示标签（"Sign Up"），而不是枚举常量（"SIGN_UP"）。
TEXT 帖子："Post content must be empty for this post type"	TEXT 帖子不能包含 content[] 块——只有 IMAGE/VIDEO/CAROUSEL 可以。
美元金额	始终使用微单位（×1,000,000）。

安全规则

绝不：

• 臆测业务、广告账户、广告系列、帖子、像素或定向 ID——请查询或询问。
• 跳过账户审核阶段。
• 未经用户明确批准就创建广告系列、广告组或广告。
• 未经用户同意就将任何内容设为 ACTIVE。
• 传入美元金额，而不是微型货币单位。
• 创建没有有效 post_id 的广告。
• 承诺可立即永久删除——Reddit 要求先将其存档至少 3 小时。
• 猜测定向 ID——请使用 reddit_ads_search_targeting 解析。