Twitch User Videos
Twitch User Videos 是频道公开的直播存档、精彩片段和上传视频，包含说明文字、创作者信息、媒体引用、时长、发布时间及可见互动指标。这些记录适合用于整理频道视频清单、比较内容类型、研究发布节奏和留存阶段性表现数据。
主要特性
- 按 username 获取视频通过一次来源请求，将一个公开 Twitch username 解析为该频道当前返回的视频记录。
- 存档、精彩片段与上传筛选可获取全部视频，也可使用 archive、highlight、upload 及其复数别名限定来源视频类型。
- 按时间或观看数排序可按 time 或 views 排列来源页，用于查看近期发布内容或观看数较高的视频记录。
- 标准化视频记录以 ReelVideoItem 结构返回视频标识、公开 URL、说明文字、创作者信息、媒体、时长、发布时间、音频信息和可见互动指标。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
username | 必填 | 一个公开 Twitch username，可带 @ 前缀；总长度为 1 至 64 个字母、数字、点、下划线或连字符。 |
filter_by | 可选 | 可选来源类型：all、archive、archives、highlight、highlights、upload 或 uploads。单数和复数别名会映射到同一类别。 |
sort_by | 可选 | 可选来源排序：time 或 views。 |
如何使用
提交 Twitch username，并按需选择视频类型与排序方式，再通过标准异步任务流程读取这一页来源结果。
- 准备一个公开 Twitch username，并确定要获取全部视频还是某一种受支持的视频类型。
- 将 username、filter_by 和 sort_by POST 到 /v1/twitch/user-videos，并保存返回的 task ID。
- 轮询 /v1/tasks/{task_id}，直到任务成功或失败；获得 task ID 后不要重复提交。
- 从 results.items 读取 ReelVideoItem 记录；next_cursor 只用于翻阅已保存的任务结果。
curl -X POST "https://api.socq.ai/v1/twitch/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"ninja","filter_by":"all","sort_by":"time"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 GET /v1/tasks/{task_id}?limit=50最佳使用场景
- 整理频道视频清单： 利用视频 ID、公开 URL、说明文字、媒体引用、时长和创作者信息，为已知频道建立当前视频目录。
- 比较视频类型构成： 分别运行受支持的类型筛选，并按发布时间与时长比较直播存档、精彩片段和上传视频。
- 记录发布与观看快照： 结合发布时间、可见观看或播放指标以及 collected_at，保存频道在特定采集时点的状态。
使用建议
- 填写 username 时不要粘贴个人资料 URL，只保留可选的 @ 和规则允许的 1 至 64 个字符。
- 需要查看近期发布时选择 time，需要查看当前来源页中观看数较高的记录时选择 views。
- 在保存请求配置时统一使用单数或复数类型别名，因为每一对别名最终映射到同一个来源类别。
- 不要在提交体中加入 cursor 或 results_limit；来源只返回一页，而任务结果 cursor 只翻阅 SocQ 已保存的记录。
- 纵向重复采集时按视频 ID 去重，并允许文本、媒体、音频、作者、时间和指标字段为空。
相关 API
需要其他类型的 Twitch 公开数据时，可以使用以下 API。
- Twitch Profile API — 通过一个公开 Twitch username 获取标准化账号记录，包含可用身份、简介、图片、账号状态、可见指标和采集上下文。