YouTube Search API

YouTube Search

主要特性

• 无需 URL 的视频发现无需预先知道视频 URL，即可发现公开普通视频。
• 结果排序支持按 relevance、date、rating 或公开观看数排序。
• 发布时间范围支持最近 hour、day、week、month 或 year 的发布时间范围。
• 时长与字幕筛选支持 short、medium、long 时长分类和字幕可用性筛选。
• 标准化视频结果统一返回视频资料、频道信息、缩略图、时长、发布时间和公开指标。

参数

如何使用

把查询设计成检索策略，而不是只填一个关键词。先保留足够宽度观察结果，再逐项增加筛选，才能知道是哪一个条件排除了候选。

1. 先明确问题：需要最相关内容、最新报道、高观看视频，还是有字幕的处理候选。
2. 向 /v1/youtube/search POST query、results_limit，以及这个问题真正需要的排序和筛选。
3. 把完整请求与 task_id 一起保存，再轮询 /v1/tasks/{task_id} 直到任务结束。
4. 按视频 ID 去重，保留查询与 collected_at；has_more 为 true 时继续翻页。

curl -X POST "https://api.socq.ai/v1/youtube/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"NASA Artemis","results_limit":10,"sort_by":"date","published_within":"month","duration":"medium","has_captions":true}'

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

最佳使用场景

• 主题与市场研究： 发现与产品、行业、组织、事件或新兴话题相关的公开视频。
• 创作者与竞品发现： 结合搜索结果和发布频道信息，识别相关创作者、品牌或竞品。
• 近期视频监控： 组合 date 排序和发布时间范围，获取近期视频用于审核或分析。
• 字幕处理数据集： 通过字幕筛选发现可用于字幕采集、摘要、分类或搜索的视频。

使用建议

• 测试两三个明确的查询变体，比把所有概念塞进一个长句更容易理解结果；不同变体的交集同样重要。
• 逐项添加筛选。如果一次加入发布时间、时长和字幕条件，空结果很难说明究竟哪个条件过窄。
• 监控近期内容时组合 date 与 published_within；不设时间范围的 relevance 回答的是更宽泛的问题。
• 排名并不稳定。只要结果位置或样本组成有意义，就保存请求、task ID、视频 ID 和 collected_at。
• results_limit 是上限，不是完整性保证；公开可用性与筛选条件都可能减少记录。
• 跨查询按视频 ID 去重，但保留每条结果来自哪个查询，才能继续分析相关性。
• URL 已知后使用 Videos 刷新详情，使用 Transcripts 读取可用字幕，不要反复通过搜索寻找同一条内容。

相关 API