YouTube Channel Live Videos API

YouTube Channel Live Videos

主要特性

• 规范频道 URL 支持支持 YouTube 公开频道的 /@handle、/channel/{id}、/c/{name} 和 /user/{name} 路径。
• 频道直播页发现按每个输入频道，采集其直播页当时公开展示的播出记录。
• 单频道采集深度每个频道可请求 20 至 2,000 条记录，默认值为 100。
• 标准化播出资料在来源可用时返回视频身份、标题、简介、频道、缩略图、时长、标签、发布时间和来源信息。
• 可见互动快照记录公开观看数、点赞数、评论数和 collected_at，便于进行时间点分析。
• 异步结果交付保留 task_id、轮询任务状态，并通过 cursor 分页稳定读取异步结果。

参数

如何使用

提交规范的公开频道 URL，并为每个频道选择采集深度。请求会创建异步任务，因此任务完成和结果读取是两个独立步骤。

1. 准备一个或多个公开 YouTube 频道 URL，使用受支持的 handle、频道 ID、自定义名称或用户路径。
2. 向 /v1/youtube/channel-live-videos POST urls 和 results_limit，并保留返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务进入 succeeded 或 failed。
4. 通过 /v1/tasks/{task_id}?limit=50 读取结果；has_more 为 true 时，把 next_cursor 作为 cursor 继续请求。

curl -X POST "https://api.socq.ai/v1/youtube/channel-live-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/@YouTube"],"results_limit":20}'

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

最佳使用场景

• 播出内容清单： 为选定频道建立结构化的公开播出记录清单。
• 直播栏目研究： 比较长期制作直播节目的频道在标题、时间、时长和发布节奏上的差异。
• 创作者播出监测： 跟踪创作者、品牌、媒体或竞品频道直播页上公开可见的播出记录。
• 播出后表现快照： 把公开观看、点赞和评论数连同采集时间保存下来，用于后续趋势比较。
• 公开媒体目录补全： 为搜索、报表或分类系统补充标准化播出资料和来源频道信息。

使用建议

• results_limit 会分别应用到每个频道。5 个 URL 配合 100 的上限，在任务级去重前最多请求 500 条记录。
• 频道 URL 必须带有非空的 handle、频道 ID、自定义名称或用户名；只有 /channel 而没有 ID 时无法解析来源。
• 以频道直播页作为内容范围边界；正在直播、即将开始和已经结束的记录会随频道及采集时间变化。
• 不要根据 type 或 extra.content_type 推断可靠的直播状态；标准化响应没有专门的正在直播、即将开始或已经结束字段。
• 响应只包含资料和缩略图引用，不包含直播聊天、可播放的流地址、字幕或文稿。
• 不同频道 URL 可能发现同一视频；任务保存结果时先按标准化视频 ID 去重，没有 ID 时再按 URL 去重。
• 任务翻页的 limit 与 results_limit 不是同一参数：每页可读取 1 至 500 条已保存结果，并持续使用不透明 next_cursor，直到 has_more 为 false。
• 公开资料不会解锁私密或会员专享播放权限；来源若返回 extra.is_members_only，应保留这个分类信号。

相关 API