TikTok Popular Songs
TikTok 原声是帖子使用的音频，这个接口让你选择 TikTok App 的 Top 50 或 Viral 50 歌曲榜。每条结果用曲名、艺术家和原声 ID 标识一段具体音频，方便整理音乐清单，再查找这段原声的详情或使用它的视频。
主要特性
- 选择要查看的歌曲榜chart_type 填 top 获取 Top 50，填 viral 获取 Viral 50。这是 TikTok App 中两个不同名称的歌曲榜；先选定一个榜，再设置最多想获取多少首，数量不能超过 50。
- 确认歌名对应哪一段原声把曲名、艺术家、原声 ID、封面和时长放在一起查看。即使两段音频名称相同，也可以通过原声 ID 区分，并用同一 ID 继续查询 TikTok Song 或 TikTok Song Videos。
- 查看使用该原声的视频数量数据源提供数量时，metrics.videos_count 表示使用这段原声的视频数。它不是听众人数、播放次数或点赞数；来源没有提供时保留 null，不把缺失值当成零。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
chart_type | 可选 | 可选榜单类型：top 选择 TikTok App 的 Top 50，viral 选择 Viral 50，默认 top。例如把示例中的 top 改为 viral，即可查询另一份榜单。 |
results_limit | 可选 | 可选歌曲数量上限，只接受 1 到 50 的整数，默认 20。例如填 10，表示从选定榜单最多获取 10 首；来源可能返回更少，读取结果分页也不会扩大这个数量上限。 |
如何使用
提交后，数据会在后台收集，因此首次响应先返回任务编号 task_id；使用这个编号查询进度，等任务完成后再读取结果。
- 先选择 chart_type：top 表示 Top 50，viral 表示 Viral 50；不填写时默认 top。results_limit 默认 20，只能填写 1 到 50 的整数，例如 20 表示最多取 20 首，实际结果可能更少。
- 将 $SOCQ_API_KEY 替换为自己的 API key，或先设置同名环境变量。按示例填写 Authorization 请求头，把 JSON 发送至 POST /v1/tiktok/popular-songs，并保存返回的 task_id。
- 采集在后台进行，所以首次响应先返回任务编号。用 GET /v1/tasks/{task_id} 查询进度；queued、running、retrying 表示尚未完成，succeeded 后读取结果，failed 时查看 error_message。
- 在 data.results.items 中读取歌曲记录。audio.id 是原声 ID，audio.artist 是艺术家名称，metrics.videos_count 是来源提供的使用该原声的视频数；items 为空表示本次没有返回记录。
- 若 data.results.has_more 为 true，把 next_cursor 原样作为 cursor 传给 GET /v1/tasks/{task_id}?cursor=...，直到 has_more 为 false。这样读取的是同一任务已经保存的下一页，不会把歌曲榜的采集上限扩大到 50 首以上。
curl -X POST "https://api.socq.ai/v1/tiktok/popular-songs" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"chart_type":"top","results_limit":20}'最佳使用场景
- 制作待查看的音乐清单： 选择 Top 50 或 Viral 50，把曲名、艺术家、原声 ID、时长及可用的视频数量导出成表格。团队可以逐项打开原声页面，人工判断哪些音频适合当前的内容想法。
- 收集使用某段原声的视频例子： 把结果中的原声 ID 作为 music_ids 传给 TikTok Song Videos，获取公开视频例子，再由你查看这些视频如何使用音频。歌曲榜接口本身不会分析视频内容或总结使用方式。
- 比较自己保存的多次榜单结果： 每次查询时保存 chart_type、原声 ID、可用的视频数量和 collected_at，再按原声 ID 关联表格，比较返回歌曲及使用数量的变化。这样的比较由你保存的数据完成，接口本身不提供历史排名。
使用建议
- 比较分次保存的结果时保持 chart_type 一致。从 top 换成 viral 就是在查看另一份榜单，歌曲列表不同本身不能说明某首歌热度上升或下降。
- 用 audio.id 关联多次任务记录，或继续调用 TikTok Song、TikTok Song Videos。只用曲名无法区分名称相同的不同音频片段。
- audio.url 为 null 时，仍可保留原声 ID 和公开原声页面链接继续查找；返回音频地址时，把它视为采集时可用的媒体链接，不要假设是永久下载地址。
相关 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 Top Search API — 按关键词查找视频和图片帖子，获取文案、创作者和互动计数。
- TikTok User Live API — 按用户名查看账号是否正在直播，以及可获取的直播间信息。