TikTok User Videos API

TikTok User Videos

主要特性

• 按已知账号采集视频流接收一个或多个 TikTok username，并独立遍历每个公开个人资料视频流，使结果始终限定在选定账号，而不是关键词或标签发现范围。
• 视频与创作者详情返回视频 ID 和 URL、文案、语言、创作者身份、媒体引用、时长、标签、提及、音乐和公开内容标记。
• 带时间的互动信号将可见播放、点赞、评论、分享、收藏和转发计数与发布时间、采集时间配对，形成特定时点的账号视频记录。
• 可控的逐账号遍历对每个 username 应用 latest 或 popular 排序及可选地区参数，同时按视频 ID 去重并执行所请求的逐账号数量上限。

参数

如何使用

把已知公开 username 提交为异步任务，再通过结果 cursor 分页读取带来源账号的标准视频记录。

1. 准备一个或多个公开 TikTok username，并选择 latest 或 popular 排序、可选的两字母地区代码和逐 username 的 results_limit。
2. 向 /v1/tiktok/user-videos POST usernames 与可选控制参数，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /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/user-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@loganpaul"],"results_limit":20,"sort_by":"latest"}'

# 轮询 GET /v1/tasks/{task_id}，再读取 data.results.items，并继续传 results.next_cursor。

最佳使用场景

• 建立创作者视频清单： 按视频 ID、规范 URL、文案、媒体、发布时间和 extra.input_username 索引选定账号，维护可追溯的公开内容清单。
• 比较发布与互动表现： 结合 created_at 与可见播放、点赞、评论、分享、收藏和转发计数比较已知账号，同时保留 collected_at 作为快照时间。
• 研究创意内容形式： 利用文案、语言、时长、标签、提及、音乐、媒体类型和公开内容标记，比较选定个人资料视频流中的重复创意模式。

使用建议

• 提交前将所有账号名统一为一种格式并去重，因为 creator 与 @creator 指向同一账号，否则可能被分别处理。
• 设置 results_limit 时同时考虑 username 数量，因为该上限和初始积分预估都会独立应用到每个提交账号。
• 需要按时间查看时使用 latest；popular 表示来源排序，不应把它理解为 SocQ 计算的评分。
• 只把 region 当作可见范围控制，不要据此认定返回视频制作于该地区。
• 合并重复任务时按视频 id 去重，同时保留 extra.input_username 和 collected_at，以维持账号归属和快照时间。
• 下游代码应把可选创作者、互动、媒体、音乐和内容标记字段按可空值处理，展示公开文案前进行转义，也不要假设来源媒体 URL 永久有效。

相关 API