TikTok Trending Feed
TikTok 热门动态视频是特定地区环境下公开展示的视频条目，包含视频与创作者身份、文案、封面、时间和可见互动指标。这些内容与表现信号适合保存地区发现快照、研究当前创意形式和进行特定时点的横向比较。
主要特性
- 按地区获取公开视频动态接收非空 region 值，并获取该地区请求环境当前公开展示的视频动态。
- 标准化视频与创作者详情以一致记录返回视频 ID 和来源 URL、文案、创作者身份、封面引用、创建时间和采集时间。
- 可见互动指标为每条返回视频集中保留公开的播放、点赞、评论、分享和收藏计数。
- 有明确边界的当前快照从一次地区视频动态响应中按 results_limit 截取结果，不继续请求来源分页，得到当前视频样本而非排名或历史序列。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
region | 必填 | 必填的非空地区值。后端会去除首尾空格并转为大写；建议使用 US 这类标准两字母地区代码，以获得预期地区环境。 |
results_limit | 可选 | 可选整数上限，范围为 4 到 2,000，默认 100；它从单次视频动态响应中截取结果，因此实际视频数可能更少。 |
如何使用
把地区视频动态请求提交为异步任务，再通过任务结果 cursor 分页读取标准化视频。
- 填写非空 region 值；建议使用 US 这类标准两字母地区代码，并将 results_limit 设为 4 到 2,000，或保留默认值 100。
- 向 /v1/tiktok/trending-feed POST region 和 results_limit，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /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
需要其他类型的 TikTok 公开数据时，可以使用以下 API。
- TikTok Profiles API — 按 username 获取公开主页身份、简介、账号标记和受众计数。
- TikTok Hashtags API — 按指定标签采集公开视频、创作者、媒体、声音和互动指标。
- TikTok Comments API — 采集公开顶级评论、作者、互动、提及和创作者互动标记。
- TikTok Videos API — 从视频 URL 获取创作者、文案、媒体、音乐、标签、提及和互动信息。
- TikTok Search API — 按关键词搜索公开视频，并支持排序和发布时间筛选。
- TikTok Comment Replies API — 使用 TikTok 视频 URL 和 comment_id 采集一条已知评论下的公开回复，返回作者、互动、时间和父评论上下文。
- TikTok Followers List API — 采集公开粉丝列表中可见的标准化资料，并保留来源上下文和支持的指标。
- TikTok Following List API — 采集 TikTok 账号公开可见的关注对象，返回标准化身份、简介、可见指标和来源账号信息。
- TikTok User Videos API — 按 username 采集公开个人资料视频，返回文案、创作者、媒体、时间、互动和来源账号上下文。
- TikTok Live Room Info API — 使用配对的直播间 ID 和主播 ID 查询一个已知直播间，返回状态、主播信息、封面和受众计数。
- TikTok Video Transcript API — 从公开视频 URL 提取可用字幕文本、语言、格式和来源上下文。