TikTok Top Search
TikTok 综合搜索会围绕关键词或短语展示视频和图集，图集指由多张图片组成、可逐张查看的帖子。文案、创作者、媒体和互动计数可以帮助你比较同一主题在不同内容形式中的表达方式。
主要特性
- 一次搜索同时发现视频和图片帖子同一个关键词可以返回视频和图集，结果中的 type 字段会标明内容形式，便于把两种内容放在一起整理，或分别筛选后查看。
- 选择排序和发布时间范围可按相关性、发布时间或点赞排序，并结合发布时间范围筛选，让返回的内容更贴近你当前需要查看的主题样本。
- 把内容、作者和互动计数放在一起查看每条结果将文案、创作者信息、媒体链接及可获取的互动计数放在一起，便于了解帖子讲了什么、由谁发布，以及对应的公开互动情况。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填搜索关键词或短语，例如 coffee 或 home workout；填写想查找的主题文字，不是 TikTok 帖子链接。 |
sort_by | 可选 | 可选排序方式：relevance 按相关性排序，date 按发布时间排序，likes 按点赞排序；默认使用 relevance，想先查看与关键词相关的内容时可保留默认值。 |
published_within | 可选 | 可选发布时间范围：day 对应昨天，week 对应本周，month 对应本月，three_months 对应最近三个月，six_months 对应最近六个月；留空时不额外限制发布时间。 |
region | 可选 | 可选两位地区代码，例如 US 或 GB，用于调整搜索时内容的可访问性；填写 US 不代表返回的帖子都发布于美国，也不代表创作者都位于美国。 |
results_limit | 可选 | 可选内容记录数量上限，接受 1 到 2000 的整数，默认 100；视频和图集都计入这个总数，例如 20 表示两种形式合计最多 20 条，实际结果可能更少。 |
如何使用
提交后，数据会在后台收集，因此首次响应先返回任务编号 task_id；使用这个编号查询进度，等任务完成后再读取结果。
- 输入主题关键词，选择更适合当前目的的相关性、时间或点赞排序，并设置数量上限；有需要时再补充发布时间范围或地区选项。
- 运行下方示例前，将 $SOCQ_API_KEY 替换为你自己的 API key，或先设置同名环境变量。按示例填写 Authorization 请求头，将 JSON 输入发送至 POST /v1/tiktok/top-search，并保存响应中的 task_id。
- 将保存的编号填入 GET /v1/tasks/{task_id} 查询进度。queued 表示排队，running 表示处理中，retrying 表示正在重试；等到 succeeded 再读取结果，若状态为 failed 则查看 error_message 中的失败原因。
- 任务成功后，读取 data.results.items，其中每一项描述一条视频或图集帖子。列表为空表示任务已完成，但没有返回记录。
- 若 data.results.has_more 为 true，next_cursor 的值就是下一页结果的标记。将它原样作为 cursor 参数填入 GET /v1/tasks/{task_id}?cursor=...，继续读取直到 has_more 为 false，即可取完该任务已保存的结果。
curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","sort_by":"relevance","results_limit":20}'最佳使用场景
- 整理某个主题的内容样本： 搜索 coffee 等主题后，将文案、创作者用户名、链接和内容形式保存为查看表，收集同一主题的视频与图片帖子例子。
- 比较返回帖子的互动情况： 将可获取的点赞、评论、分享计数与内容形式、发布时间放在同一张表中，并保留关键词和筛选条件，方便后续比较样本而不混淆其来源。
使用建议
- 展示结果前先查看 type 和 media；photo_carousel 表示图片图集，应使用图片列表或轮播展示，不使用视频播放器。
- 收集多个关键词时，用帖子 ID 去除重复匹配，并保留每次查询的关键词，避免同一帖子因匹配多个词而被重复统计。
- 后续流程只接受视频时可使用 TikTok Search，需要同时研究视频和图片帖子时则使用 Top Search，并在展示中处理两种形式。
- 图集缺少时长或播放计数时，将对应指标保留为空，不要解释为零秒视频或没有人看过的帖子。
相关 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 Trending Feed API — 按 region 采集当前公开视频动态，返回创作者、文案、封面、时间和可见互动指标。
- TikTok Video Transcript API — 从公开视频 URL 提取可用字幕文本、语言、格式和来源上下文。
- TikTok Search Users API — 按关键词搜索 TikTok 公开账号。
- TikTok Song API — 通过片段 ID 或音乐 URL 获取公开原声元数据。
- TikTok Song Videos API — 按指定原声 ID 采集使用该原声的公开视频。
- TikTok Popular Songs API — 获取 TikTok App 的 Top 50 或 Viral 50 歌曲榜，查看曲名、艺术家、原声 ID 及使用该原声的视频数。
- TikTok User Live API — 按用户名查看账号是否正在直播，以及可获取的直播间信息。