tiktok-ads

TikTok Ads

用于管理 TikTok 广告投放的战略指南。深入调研、仔细验证参数，并引导用户满足平台针对不同目标的严格要求。

此技能适用于付费 TikTok 广告（TikTok Marketing API 接口）。

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已连接 TikTok Marketing 集成（TikTok Ads Manager / Business Center），访问 https://app.hyperfx.ai/apps。

如果 search("tiktok_ads_advertiser_accounts_list") 没有找到 tiktok_ads_advertiser_accounts_list，请停止操作，并告知用户启用 Hyper MCP 并连接 TikTok Marketing。

如何运行此技能中的工具

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

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

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

不在此技能范围内——转交其他技能

• TikTok 自然内容发布（视频、照片、轮播内容——不涉及广告支出）→ tiktok。
• 创意生成（广告文案、图片）→ ad-creative-generation；视频创意 → video-generation。
• 跨平台广告系列投放 → 使用此技能处理 TikTok，然后分别调用 meta-ads / google-ads。

工具接口

工具	用途
tiktok_ads_advertiser_accounts_list	发现：列出已连接用户可用的广告主 ID。
tiktok_ads_campaigns_get、tiktok_ads_campaigns_create、tiktok_ads_campaigns_update、tiktok_ads_campaigns_status_update	广告系列生命周期管理。
tiktok_ads_ad_groups_list、tiktok_ads_ad_groups_create、tiktok_ads_ad_groups_update、tiktok_ads_ad_groups_status_update	广告组生命周期管理。
tiktok_ads_list、tiktok_ads_create、tiktok_ads_ad_status_update、tiktok_ads_update	广告生命周期管理及受支持的增量内容更改。编辑前请先描述所选工具；Smart+ 广告请使用专用工具。
tiktok_ads_videos_upload、tiktok_ads_videos_get、tiktok_ads_videos_search	上传及查找视频创意。
tiktok_ads_integrated_reports_get	效果报告。
tiktok_ads_custom_audiences_create、tiktok_ads_custom_audiences_list、tiktok_ads_lookalike_audiences_create	受众管理（可选）。

阶段 1：账户发现

初始设置

• 使用 tiktok_ads_advertiser_accounts_list() 获取广告主 ID。
• 如果有多个账户：请用户选择一个。
• 如果只有一个账户：告知用户并继续。

出价基准（可选，但建议使用）

设置出价前，调用 tiktok_ads_benchmarks_get 获取行业专属 CPM/CPC 基准。这有助于避免使用占位值，导致出价过低而无法赢得竞价，或出价过高而超出用户预算。

tiktok_ads_benchmarks_get(
    advertiser_id="123456789",
    dimensions=["industry"],
    filtering={"industry": "292801"}  # industry code from tiktok_ads_advertiser_accounts_list
)

可用的广告系列目标

目标	最适用于	关键要求
TRAFFIC	提升网站访问量	promotion_type="WEBSITE"，按 CPC 计费
CONVERSIONS	促进购买/获取潜在客户	Pixel ID、转化事件追踪
REACH	提升品牌知名度	仅限手动版位、按 CPM 计费、频次上限
APP_PROMOTION	推广应用安装	应用 ID、应用商店 URL
VIDEO_VIEW	提升视频互动	视频创意素材

阶段 2：创建广告系列

步骤 1：创建广告系列

预算要求：

• 最低 50 美元的广告系列级预算（TikTok 要求）。
• budget_mode：BUDGET_MODE_INFINITE（CBO）、BUDGET_MODE_DAY 或 BUDGET_MODE_TOTAL。

tiktok_ads_campaigns_create(
    advertiser_id="123456789",
    campaign_name="Summer Sale 2026",
    objective_type="TRAFFIC",
    budget_mode="BUDGET_MODE_DAY",
    budget=50.0,  # MINIMUM $50/day
    operation_status="ENABLE"
)

步骤 2：创建广告组

始终必填的参数：

• advertiser_id、campaign_id、adgroup_name。
• location_ids（例如，美国使用 ["6252001"]）。
• schedule_type 和 schedule_start_time（必须为未来日期）。
• billing_event（CPC、CPM、OCPM）。
• budget_mode（广告组必填）。

对于 TRAFFIC 广告系列：

tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Website Traffic - Summer Sale",
    location_ids=["6252001"],  # US
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",  # FUTURE DATE
    billing_event="CPC",
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    promotion_type="WEBSITE",        # REQUIRED for TRAFFIC
    optimization_goal="CLICK",       # REQUIRED (correct spelling)
    bid_price=0.50,
    placement_type="PLACEMENT_TYPE_AUTOMATIC",
    operation_status="ENABLE"
)

对于 REACH 广告系列：

tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Brand Awareness US",
    location_ids=["6252001"],
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",
    billing_event="CPM",                       # REQUIRED for REACH
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    optimization_goal="REACH",
    placement_type="PLACEMENT_TYPE_NORMAL",    # REQUIRED — automatic NOT supported
    placements=["PLACEMENT_TIKTOK"],           # REQUIRED
    bid_price=2.0,                             # REQUIRED
    frequency=3,                               # REQUIRED
    frequency_schedule=7,                      # REQUIRED
    operation_status="ENABLE"
)

步骤 3：上传创意素材

为每个创意变体上传一个视频。记录返回的 video_id，你将在步骤 4 中用到它。

video_response = tiktok_ads_videos_upload(
    advertiser_id="123456789",
    video_file=video_data,
    upload_type="UPLOAD_BY_FILE"
)
video_id = video_response["data"]["video_id"]

已上传的视频可以重复使用。使用 tiktok_ads_videos_search 按名称查找现有视频，或使用 tiktok_ads_videos_get 获取已知视频 ID 的元数据。

步骤 4：创建广告

tiktok_ads_create(
    advertiser_id="123456789",
    adgroup_id="1234567890123456",
    ad_name="Summer Sale - Hero Video",
    identity_type="CUSTOMIZED_USER",   # or "AUTH_CODE" for TikTok Account spark ads
    identity_id="<advertiser_identity_id>",
    ad_format="SINGLE_VIDEO",
    video_id=video_id,
    ad_text="Limited-time summer drop. Shop now.",
    landing_page_url="https://example.com/summer",
    call_to_action="SHOP_NOW",
    operation_status="DISABLE"        # create paused, enable after review
)

始终以暂停状态创建广告（operation_status="DISABLE"），只有在用户审核后才将其切换为 ENABLE。

关键参数规则

常见错误与解决方案

错误	解决方案
预算必须至少为 $50	TikTok 对广告系列预算设定了 $50 的最低限额。
开始时间已过	在 schedule_start_time 中使用未来日期和当前年份。
TikTok API 在某些场景下会拒绝 optimize_goal	架构中同时存在 optimize_goal 和 optimization_goal，但建议优先使用 optimization_goal——它是 TikTok 在大多数目标类型中验证的字段。
仅支持手动版位	REACH 要求使用 placement_type="PLACEMENT_TYPE_NORMAL"。
出价必须大于 $0	将 bid_price 设为大于 0。
请设置频次上限	REACH 要求同时设置 frequency 和 frequency_schedule。

参数依赖关系

TRAFFIC 目标要求：

• promotion_type="WEBSITE"。
• optimization_goal="CLICK"。
• billing_event="CPC"。
• bid_price > 0。

REACH 目标要求：

• optimization_goal="REACH"。
• billing_event="CPM"。
• placement_type="PLACEMENT_TYPE_NORMAL"。
• placements 数组（例如，["PLACEMENT_TIKTOK"]）。
• bid_price > 0。
• frequency 和 frequency_schedule。

CONVERSIONS 目标要求：

• 已关联 TikTok Pixel，且已配置转化事件。
• optimization_goal="CONVERT"（或基于价值的目标使用 VALUE）。
• billing_event="OCPM"。
• 在广告组上设置 pixel_id 和 external_action。

报告

tiktok_ads_integrated_reports_get(
    advertiser_id="123456789",
    report_type="BASIC",
    data_level="AUCTION_AD",
    dimensions=["ad_id"],   # ID-based only — NOT names
    start_date="2026-04-01",
    end_date="2026-04-30",
    metrics=["impressions", "clicks", "ctr", "spend", "cpc", "cpm"],
    page_size=20
)

报告规则：

• 使用 stat_time_day 维度时：每次调用的日期范围最多为 30 天。
• 仅使用基于 ID 的维度（ad_id、campaign_id、adgroup_id，而非名称）。
• 转化指标（conversion、cost_per_conversion、conversion_rate 等）要求已关联 Pixel，且已配置转化事件。
• data_level 必须与维度粒度匹配：ad_id 对应 AUCTION_AD，adgroup_id 对应 AUCTION_ADGROUP，campaign_id 对应 AUCTION_CAMPAIGN。

安全规则

切勿：

• 在未提醒用户的情况下，将广告组预算设为低于 $20/天。
• 将广告系列安排在已过的 schedule_start_time 开始（TikTok 会因此返回令人困惑的错误）。
• 将 REACH 广告组与 PLACEMENT_TYPE_AUTOMATIC 混用——这会导致验证悄无声息地失败。
• 在用户审核创意素材和定向设置之前，以 operation_status="ENABLE" 创建广告。
• 使用基于名称的维度运行报告——TikTok 只接受 ID 维度。