YouTube Playlist Videos API

YouTube Playlist Videos

主要特性

• 多播放列表 URL 与 ID 输入一个任务可处理多个公开播放列表 URL 或原始播放列表 ID，并为每个成功解析的播放列表分别应用 results_limit。
• 标准化视频目录记录以一致结构返回视频 ID、标题、规范 URL、频道身份、单张缩略图、秒数时长和采集时间。
• 播放列表与所有者来源保留播放列表 ID、播放列表标题、可读时长，并在视频条目缺少频道字段时使用播放列表所有者信息补充来源。

参数

如何使用

把已知的公开播放列表地址或 ID 作为异步任务提交，任务成功后再逐页读取持久化的标准化视频记录。

1. 准备一个或多个带有 list 查询值的公开播放列表 URL，或直接准备原始播放列表 ID，并移除重复引用。
2. 把 urls 和 10 到 2,000 之间的可选 results_limit POST 到 /v1/youtube/playlist-videos，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务状态为 succeeded 或 failed。
4. 读取 data.results.items；results.has_more 为 true 时继续传入 results.next_cursor，并将播放列表 ID、视频 ID 与来源集合核对。

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

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续传入 next_cursor

最佳使用场景

• 公开播放列表清单： 利用视频 ID、标题、URL、频道身份、缩略图、时长和播放列表来源，为选定的公开播放列表建立结构化清单。
• 课程与系列内容索引： 把播放列表标题与视频标题、频道信息、时长和来源链接一起编入索引，用于整理公开课程、演讲或系列内容。
• 视频信息补充种子列表： 将返回的规范视频 URL 和 ID 去重后，作为单独获取详情、字幕、审核或归档的任务队列。

使用建议

• 输入原始播放列表 ID，或确保 URL 的 list 查询值非空；系统不会使用其它 URL 部分解析播放列表，缺少 list 值的 URL 会被跳过。
• 把 results_limit 视为每个播放列表首次返回视频数组的上限，不要将它理解为大型播放列表的深度完整性保证。
• 批量提交前把同一播放列表统一为一种写法，因为系统只会移除完全相同的字符串，同一 ID 的不同 URL 变体仍可能重复处理。
• 将返回的 extra.playlist_id 和视频 id 与输入集合核对，因为私密、删除、受限、隐藏、格式错误或不可访问的条目可能缺失。
• 使用 collected_at 追踪记录；需要发布时间或互动指标时另行获取视频详情，因为 metrics 为空且 created_at 为 null。

相关 API