Douyin User Videos API

Douyin User Videos

主要特性

• 两种创作者定位方式可提交受支持的抖音主页 URL，也可直接提交已知 user_id；同时填写时，backend 优先使用 user_id。
• 清晰的一页范围results_limit 可在 1 至 20 之间选择，默认与最大值均为 20；provider 请求始终从首个来源页开始。
• 内容与作者信息同一结构返回每条 reel-video 记录统一保留可用文案、公开作者字段、来源 URL、时间、媒体引用和视频时长。
• 适合留存的互动观察值将可获得的播放、点赞、评论、分享和浏览数与 collected_at 一并返回，明确每次观察发生的时间。

参数

如何使用

提交一个公开创作者标识，等待异步任务完成，再读取已存储的标准化视频结果。

1. 准备 douyin.com 或 iesdouyin.com 上路径包含 /user/{identifier} 的主页 URL，或者一个已知 user_id。
2. 向 /v1/douyin/user-videos POST 标识及可选的 1 至 20 results_limit，并保存 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
4. 读取 data.results.items；只有 SocQ 已存储记录仍有下一页时才继续使用 next_cursor，它不会请求新的来源页。

curl -X POST "https://api.socq.ai/v1/douyin/user-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"'"$DOUYIN_PROFILE_URL"'","results_limit":20}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；next_cursor 仅用于已存储结果

最佳使用场景

• 创作者视频快照： 在指定观察时点保存一个范围受限的公开视频集合，并保留每条记录的采集时间。
• 视频目录补全： 为已有创作者记录补充标准化文案、作者身份、来源 URL、发布时间、时长和可用媒体。
• 创意与格式整理： 依据返回的文案、时长和媒体字段，对现有视频的内容呈现或格式做结构化归类。
• 同次快照内的互动比较： 在保留 collected_at 的前提下，对比这批视频中可见的播放、点赞、评论、分享与浏览数据。

使用建议

• 每次请求尽量只提交一种身份字段；url 与 user_id 同时存在时，backend 会选择 user_id。
• 提交前同时校验 URL host 和 /user/{identifier} 路径；普通视频 URL 不符合此 endpoint 的输入契约。
• 只有确实需要少于 20 条结果时才设置 results_limit，其取值必须是 1 至 20 的整数。
• 不要把任务结果 cursor 当作抖音来源 cursor；provider 始终请求首个来源页，SocQ cursor 只读取已存储记录。
• 作者、媒体、时长、发布时间和单项指标都可能为空；存储观察结果时可结合 id 与 collected_at。

相关 API