TikTok User Live
TikTok 账号的直播状态描述某一时刻是否正在开播，正在进行的直播还可以有房间标题、封面和观看人数。将状态与创作者和对应时间放在一起，可以确认当时哪些账号正在直播，并判断这条状态信息距离现在有多久。
主要特性
- 区分正在直播与当前离线每次成功查询都会返回 is_live，true 表示正在直播，false 表示离线，因此没有开播的账号仍会有一条状态记录，不会仅因离线而从结果中消失。
- 了解正在进行的直播间直播记录可提供房间标题、创作者名称、封面和观看人数，让你在判断是否开播之外，还能查看这场直播的基本信息。
- 从用户名开始批量查询一次可以查询多个公开用户名，无需先找到 room_id 和 user_id，而这两个标识是另一个直播间详情接口所需的输入。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
usernames | 必填 | 必填用户名列表，至少一项，可带或不带 @；在 Playground 中每行填写一个用户名，代码请求中使用 ["thejustalex", "@tiktok"] 这样的 JSON 数组，不填写主页链接，也不能只填写 @。 |
如何使用
提交后，数据会在后台收集，因此首次响应先返回任务编号 task_id；使用这个编号查询进度，等任务完成后再读取结果。
- 准备一个或多个公开用户名，不使用主页或直播间链接；可以从账号主页复制 @ 后面的用户名。
- 运行下方示例前，将 $SOCQ_API_KEY 替换为你自己的 API key，或先设置同名环境变量。按示例填写 Authorization 请求头，将 JSON 输入发送至 POST /v1/tiktok/user-live，并保存响应中的 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/user-live" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["thejustalex"]}'最佳使用场景
- 制作账号直播状态表： 把每个创作者、直播或离线状态、采集时间放在同一张表中，方便查看提交的账号在最近一次观察时有哪些正在开播。
- 整理可以打开查看的直播间： 筛选 is_live=true 的记录，将房间链接、标题和观看人数组成待查看列表，便于逐个打开正在进行的直播。
使用建议
- 提交重复用户名列表前，去掉开头的 @ 并按不区分大小写的方式去重，避免 tiktok 和 @TikTok 让按输入数量计算的预估费用增大。
- 结果为 is_live=false 时展示为离线，并省略缺失的房间信息，不要将这条成功查询显示为账号查询失败。
- 自行定期刷新状态表时，在状态旁标明采集时间 collected_at，避免把较早的结果误认为刚刚观察到的状态。
- 已有对应的 room_id 和 user_id 且需要单独查询房间时，使用 TikTok Live Room Info，不要将这些 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 Popular Songs API — 获取 TikTok App 的 Top 50 或 Viral 50 歌曲榜，查看曲名、艺术家、原声 ID 及使用该原声的视频数。
- TikTok Top Search API — 按关键词查找视频和图片帖子，获取文案、创作者和互动计数。