TikTok Live Room Info API

TikTok Live Room Info

主要特性

• 配对查询直播间与主播使用同一直播间的 room_id 和主播 user_id 进行查询，最多返回一条标准化 live_room 记录。
• 直播间与主播上下文同时返回当前直播标题和状态，以及主播的公开 ID、username 与显示名称。
• 受众与封面快照记录查询时可见的观看人数、点赞数、公开封面和采集时间，便于按时点解释结果。

参数

如何使用

准备同一个已知活跃直播间的两个标识，提交异步查询，再从任务结果读取标准化快照。

1. 从能提供当前 TikTok 直播信息的来源取得 room_id，并从同一上下文或 TikTok Profiles 结果取得对应主播的 user_id。
2. 把两个非空字符串 POST 到 /v1/tiktok/live-room-info。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /v1/tasks/{task_id}?limit=50 读取 data.results.items；成功解析时最多产生一条记录，只有 results.has_more 为 true 时才继续传 next_cursor。

curl -X POST "https://api.socq.ai/v1/tiktok/live-room-info" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"room_id":"7523685855395842871","user_id":"6742945285876515845"}'

# 轮询 GET /v1/tasks/{task_id}，再通过 /v1/tasks/{task_id}?limit=50 读取 data.results.items。

最佳使用场景

• 按时点核对直播状态： 结合返回的状态、标题、直播间 ID 和 collected_at，确认一个已知直播间在采集时的可见状态。
• 制作受众快照报告： 把 viewers_count、likes_count 与 collected_at 一同保存，比较同一场已知直播在不同采集时点的观测值。
• 补全直播间资料： 为已有直播间记录补充主播 ID、username、显示名称、直播标题、状态和封面。

使用建议

• 确保 room_id 与 user_id 来自同一场正在进行的直播；直播间与主播不匹配时，可能没有结果或返回与输入有关的来源错误。
• 始终把两个标识保存为字符串，避免较长的 TikTok 数字 ID 被客户端或数据库舍入。
• 在预计直播仍在进行时发起查询；空结果可能表示直播已结束、不可用、标识无效或两者不匹配，并不代表接口发现了一条离线直播记录。
• 使用 collected_at 作为状态和指标的观测时间；标准化记录中的 created_at 为 null，url 为空字符串。

相关 API