TikTok Trending Feed API

TikTok Trending Feed

主要特性

• 按地区获取公开视频动态接收非空 region 值，并获取该地区请求环境当前公开展示的视频动态。
• 标准化视频与创作者详情以一致记录返回视频 ID 和来源 URL、文案、创作者身份、封面引用、创建时间和采集时间。
• 可见互动指标为每条返回视频集中保留公开的播放、点赞、评论、分享和收藏计数。
• 有明确边界的当前快照从一次地区视频动态响应中按 results_limit 截取结果，不继续请求来源分页，得到当前视频样本而非排名或历史序列。

参数

如何使用

把地区视频动态请求提交为异步任务，再通过任务结果 cursor 分页读取标准化视频。

1. 填写非空 region 值；建议使用 US 这类标准两字母地区代码，并将 results_limit 设为 4 到 2,000，或保留默认值 100。
2. 向 /v1/tiktok/trending-feed POST region 和 results_limit，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /v1/tasks/{task_id}?limit=50 读取 data.results.items，并在 results.has_more 为 true 时继续传 results.next_cursor。

curl -X POST "https://api.socq.ai/v1/tiktok/trending-feed" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region":"US","results_limit":20}'

# 轮询 GET /v1/tasks/{task_id}，再读取 data.results.items，并继续传 results.next_cursor。

最佳使用场景

• 保存地区发现快照： 保存一次地区请求返回的视频 ID、来源 URL、文案、创作者和 collected_at，记录采集时公开展示的视频集合。
• 抽样研究当前创意： 结合文案、创作者名称、封面和创建时间，比较选定地区视频动态中可见的创意构成。
• 比较可见互动表现： 将播放、点赞、评论、分享和收藏计数与 collected_at 结合，横向比较返回视频的公开互动信号。

使用建议

• 即使当前运行时只要求非空值，也应使用标准两字母地区代码；后端会去除首尾空格并转为大写。
• 把 results_limit 当作上限而不是预期数量，因为此接口只截取一次视频动态响应，不会继续请求来源分页。
• 只把 region 解释为视频动态的可见环境，不要据此判断视频来源；extra.region 是单条记录数据，可能为空或与请求值不同。
• 任务结果 cursor 只对 SocQ 已保存的记录分页，不会从地区视频动态继续获取另一页。
• 比较重复任务时按视频 id 去重并保留 collected_at，因为不同请求之间的视频集合和顺序可能变化。
• 下游代码应把创作者、互动指标、封面、时间和 extra 值按可空字段处理，并在展示公开文案前进行转义。

相关 API