YouTube Videos API

YouTube Videos

主要特性

• 已知 URL 批量查询一个请求可以查询多个已知的公开视频和 Short URL。
• 稳定的视频身份每条结果统一返回视频 ID、规范 URL、标题、公开简介和发布频道。
• 内容元数据包含缩略图、时长、hashtag、发布时间和标准化内容类型。
• 时间点互动指标通过 collected_at 记录公开观看数、点赞数和评论数的采集时快照。
• 一致的视频结构普通视频和受支持的 Short URL 使用相同的标准化视频结构。

参数

如何使用

把链接收件箱转换为可关联、可搜索、可刷新的视频记录。请求异步执行，请把 task ID 与原始批次一起保存，直到所有可访问链接处理完成。

1. 收集并去重公开 watch 或 Shorts URL；频道页和搜索结果页应交给其他端点。
2. 把 urls 数组 POST 到 /v1/youtube/videos，并把返回的 task_id 绑定到来源批次。
3. 轮询 /v1/tasks/{task_id}；queued 和 running 都表示批次仍在处理中。
4. 成功后按 id 建立索引；has_more 为 true 时继续传入 next_cursor。

curl -X POST "https://api.socq.ai/v1/youtube/videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=arj7oStGLkU"]}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 GET /v1/tasks/{task_id}?limit=50

最佳使用场景

• 视频 URL 列表补全： 为已有 YouTube URL 列表补充标题、频道信息、缩略图、时长、发布时间和公开指标。
• 指定视频表现对比： 比较一组视频或 Shorts 的公开观看数、点赞数、评论数、时长和发布信息。
• 活动与竞品视频监控： 定期采集已知活动、创作者或竞品视频的公开元数据快照。
• 视频内容目录： 把标准化视频记录接入内部搜索、报表、审核、摘要或分析流程。

使用建议

• 把 id 作为主键。标题会修改，同一视频也可能通过多种有效 URL 进入系统。
• canonical_url 适合对外跳转；需要追溯线索来源时，还应保留 input_url。
• 指标描述的是 collected_at 时刻的页面状态。对比两次快照有价值，直接覆盖旧值会丢失历史。
• 简介中的链接属于外部不可信输入，在展示、抓取或导入之前必须校验。
• 没有结果不代表链接从未存在，私密、删除、限制或暂时不可访问的内容都可能从批次中缺失。
• 评论和字幕文本被刻意拆分为独立资源，只对真正进入对应流程的视频发起请求。
• 按主题发现内容请先用 Search；已经知道具体 URL 时再使用 Videos。

相关 API