TikTok Ad Library Ad API

TikTok Ad Library Ad

主要特性

• 已知广告 URL 输入提交一个路径包含 /ad 的 TikTok 官方 http 或 https URL。
• 标识派生依次优先使用首个 id 查询值、ad_id 和最右侧数字路径段；否则把 URL 作为 provider fallback。
• 单对象详情请求一个上游详情对象，并且仅在存在受支持广告标识时最多输出一条记录。
• 规范化广告字段以稳定字段返回广告主、文案、日期、国家、平台、格式、落地页、展示、媒体、发布时间和采集时间。
• 保留来源空值Commercial Content Library 与 Creative Center 记录可能暴露不同字段，无法获得的值保持为空。

参数

如何使用

提交一个已知公开广告 URL，轮询异步任务，并在可用时处理单条结果。

1. 尽量选择带 id、ad_id 或数字路径标识的 TikTok 官方广告 URL。
2. 把 url 提交到 /v1/tiktok-ad-library/ad，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务进入终止状态。
4. 成功后读取 data.results.items；详情操作返回零或一条记录。

curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://library.tiktok.com/ads/detail/?id=1871655924410641"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；详情操作最多返回一条记录

最佳使用场景

• 选定广告检查： 把搜索结果中选定的一条广告解析为当前可用的标准化详情字段。
• 创意审阅： 检查已知广告的公开创意文案、广告主身份、格式、媒体和落地页。
• 透明度归档： 保留一条包含来源 URL、展示日期、投放上下文和采集时间的公开记录。
• 跨广告库比较： 比较选定广告记录中受支持的公开元数据，而不把它当作活动效果。

使用建议

• 优先使用带明确数字 id 或 ad_id 查询值的 URL，避免依赖 provider fallback。
• URL 校验通过并不保证上游来源仍会返回可识别广告对象。
• 把 Ads Library 与 Creative Center 字段视为来源特定信息，不要假设可直接互换。
• 媒体或落地页 URL 可能过期或重定向，应仅在适用条款允许时归档。
• 不要从公开展示日期或 impressions 推断定向、花费、转化或效果。
• 需要发现时使用 search 端点；这个详情端点不会枚举广告主的广告。

相关 API