YouTube 公开数据 API:搜索与频道 | SandBase

YouTube 是互联网上最大的公开视频语料库,它的搜索、频道和字幕数据支撑着从媒体监测、内容调研到给 LLM 喂转录文本的各种流程。官方的 YouTube Data API 能做很多事,但那意味着一个带凭据的 Google Cloud 项目和一份要精打细算的每日配额;公开的 list 读取用 API key 即可,而私有和账号授权的操作需要 OAuth,字幕下载还另有一套流程。

SandBase 的 YouTube 公开数据 API 给你一条更简单的读取路径。它通过普通 REST 端点搜索 YouTube 并读取公开的视频、频道、评论和字幕——一把 SandBase API key,你这边不用建 Google Cloud 项目。下面的字段名和 JSON 结构都是用来说明大致形态的示例;具体参数和响应字段请以每个端点的在线 API 参考和一份真实响应为准。

这不是 Google 官方的 YouTube Data API。 如果你需要对自己账号做已认证操作、上传,或受 Google 管辖的配额,请用官方 YouTube Data API;当你的流程需要的是公开、只读的搜索和内容数据(调研、监测或补全)时,用 SandBase。想直接试?领取 SandBase API key,再浏览 YouTube 端点。

先说结论

• 一个 API 搜索 YouTube 并读取公开的视频、频道、评论、字幕和搜索建议。
• 本文的 Model API 端点用 POST /v1/api/youtube/<path> 调用——只传该端点的参数,不用 Google Cloud 项目,一把 SANDBASE_API_KEY。
• 端点以自然标识为入参:search_query、video_id、channel_id、channel_name 或 keyword。
• 它只返回公开、只读数据。不能上传、没有账号操作、你这边也没有 Google OAuth;鉴权用 SandBase API key。

你到底需要哪个 YouTube API?

你的需求	选择	原因
上传、管理自己的频道,或对已认证账号操作	官方 YouTube Data API	OAuth 保护的账号操作(公开 list 读取用 API key);Google 管辖的配额。
搜索并读取公开的视频、频道、评论或字幕	SandBase YouTube 公开数据 API	普通 REST、一把 SandBase key、面向只读流程的结构化 JSON。
私密或仅账号可见的数据和分析	都不适用于公开流程	频道主分析和私密数据不在本篇公开数据的范围内。

从 YouTube API 能拿到什么

整个目录横跨一个 web 面和一个更新的 web-v2 面。按用途归类:

• 搜索 —— 综合搜索、视频搜索、Shorts 搜索,以及搜索建议。
• 视频 —— 视频信息、相关视频、视频流,以及带回复的评论。
• 频道 —— 从名称或 URL 解析出 channel id,再读取频道信息、视频、Shorts 和社区帖子。
• 字幕与转录 —— 单个视频的字幕和 subtitle。

并非列出的每一项能力都已开放直接调用——我测试时有一两个端点返回了上游错误——所以动手前请以每个端点的在线 API 参考为准。

SandBase 上的 YouTube API 页面——带标签的概览,加上端点列表,每个端点标有路径。

YouTube 提供的 vs. SandBase 补上的

公开数据来自 YouTube。SandBase 并不拥有或运营 YouTube,它只是为符合条件的公开数据流程提供一个统一的 API 层。每一项能力变成一个稳定端点,鉴权收敛成一把 key,响应都是可预期的 JSON——于是 agent 可以沿着同一套约定串起”解析一个频道 → 列它的视频 → 拉某个视频的评论”,而不用再管一个 Google Cloud 项目和每日配额。

快速上手:第一次调用

SandBase 有不止一个 API 面。目录里可能会展示 /apis/v1/... 下的 GET 路径;本文用的是每个端点 API 参考里带厂商前缀的 Model API 路径。不要替换 HTTP 方法或 URL——按你所选端点的参考文档来。

从频道名称解析出 channel id:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/youtube/web/channel-id",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"channel_name": "NASA"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "YouTube request did not complete"))

data = body["outputs"][0]["data"]
# 字段名仅为示例——请以一份真实响应为准核对具体键名。
print(data.get("channel_name"), data.get("channel_id"))

curl -X POST https://api.sandbase.ai/v1/api/youtube/web/channel-id \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_name": "NASA"}'

每个响应都用同一个 SandBase 信封:一个 id、一个 status、model 名称,以及一个 outputs 数组,其中唯一一项在 data 下携带载荷。只有这个信封是保证的;data 里嵌套的业务字段由上游那一面决定,所以以端点参考和一份真实响应为准。status 可能是 pending、running、completed、failed 或 timeout——查每个端点的参考了解它的运行模式,并对 status 分支,别假设请求总是直接返回一个 completed 载荷。下面只是一个示例响应结构——里面嵌套的字段名和数值都是示例,并非保证的 schema,请以一份真实响应为准核对具体字段:

{
  "id": "3cdfb9e9-51d0-4129-82cf-055edbdc1199",
  "status": "completed",
  "model": "youtube/web/channel-id",
  "outputs": [
    {
      "data": {
        "…": "示例响应结构——请以一份真实响应为准核对其中嵌套字段"
      }
    }
  ]
}

解析频道类的端点用来给你一个 channel id,你把它带进频道和视频端点。failed 或 timeout 的请求会带上 error 而没有 outputs,所以读 outputs[0].data 之前先判 status。不同端点的响应结构不一样——先看一份真实响应,再按端点逐一对准字段路径。

端点的 API 参考是每个参数名和响应路径的权威来源。

能力地图

能力簇	代表端点	典型用途
搜索	youtube/web-v2/general-search	宽泛的话题与关键词发现
搜索建议	youtube/web-v2/search-suggestions	关键词扩展与联想调研
频道解析	youtube/web/channel-id	名称/URL → channel id
频道内容	youtube/web-v2/channel-videos	列出一个频道的视频
视频信息	youtube/web-v2/video-info	元数据、作者、分类、字幕可用性
评论	youtube/web-v2/video-comments	互动与情感分析
字幕	youtube/web-v2/video-captions	转录流水线

分页方式因端点而异——若干端点接受一个可选的 continuation_token 请求参数。查每个端点的参考,确认它是否分页以及怎么分页。

YouTube 端点列表的一部分,横跨 web 和 web-v2 两个面。

在 agent 工作流里串联调用

因为每个端点共用同一套鉴权和同一个响应信封,agent 可以从一个搜索词走到一份转录文本,而不用为每个页面单独写特例。一个常见的内容调研模式是这样:

1. 发现。 用 search_query 调 youtube/web-v2/general-search 找候选视频和频道,再从一份真实响应里读你需要的字段。
2. 解析频道。 用 channel_name 调 youtube/web/channel-id 拿到稳定的 channel_id,再调 youtube/web-v2/channel-videos 列出它的上传视频。
3. 读取视频。 用 video_id 调 youtube/web-v2/video-info 拿元数据,再调 youtube/web-v2/video-comments 和 youtube/web-v2/video-captions 拿互动和转录数据。

每一步都返回同样的 { id, status, model, outputs } 结构,所以你的 agent 只需判一次 status,读 JSON 的那段代码在每一步都能复用。

常见用例

用 YouTube 搜索 API 做话题发现

用一个 query 调 youtube/web-v2/general-search 摸清整个领域,再用 youtube/web-v2/search-suggestions 把一个种子关键词扩展成相关的联想 query。输入:query 或 keyword。输出:结果和建议列表。端点:general-search、search-suggestions。

用 YouTube 频道 API 做创作者调研

用 youtube/web/channel-id 解析一个频道,再用 youtube/web-v2/channel-videos 读它的视频。输入:频道名。输出:channel id 和它的视频列表。端点:channel-id、channel-videos。

用 YouTube 字幕 API 做转录流水线

用 youtube/web-v2/video-captions 先发现一个视频可用的字幕轨道(不带语言调用会返回轨道列表),再请求具体的 language_code 取回该轨道,喂给摘要或搜索流水线。输入:video id(加可选的 language_code)。输出:可用轨道,再是所选轨道。端点:video-captions。完整的四次调用走查,看如何搭建 YouTube 转录管道。

边界与限制

• 只读、公开数据。 不能上传、不能做账号操作,也拿不到频道主分析。
• 速率与量级。 把响应当作尽力而为的读取;遇到 HTTP 429 用退避重试。
• 参数与结构随上游而定。 标识各异(search_query、video_id、channel_id、channel_name、keyword);部分端点接受一个可选的 continuation_token 用于分页。先看真实响应、读 schema。
• 并非所有列出的端点都已可调用。 测试时有一两个端点返回了上游错误;在依赖某个具体端点之前,先对照在线 API 参考确认。
• 这不是 Google 官方合作。 SandBase 只是提供对公开数据的统一访问;请遵守 YouTube 的条款以及你使用场景下适用的规则。

常见问题

我需要 Google Cloud 项目或 YouTube OAuth 吗? 不需要。你用 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你建 Google Cloud 项目或管理 OAuth 配额。

用什么来标识视频或频道? 用自然标识:video_id、channel_id 和 channel_name。搜索用 search_query;建议用 keyword。先用 channel-id 把名称转成稳定 id。

分页怎么做? 若干端点接受一个可选的 continuation_token 请求参数用于取下一页。查每个端点的参考,确认它是否分页以及怎么分页。

能读私密视频或频道分析吗? 不能。这个 API 只返回公开数据。私密视频、仅不公开可见的数据和频道主分析都不在范围内。

能更高量级地采集字幕或评论吗? 查线上 YouTube API 列表看当前有哪些端点、各自支持什么参数,接入前先对照每个端点的参考确认可用性。

从一个搜索请求开始

创建一把 SandBase API key,用 channel-id 解析一个频道或跑一次 general-search,先看清返回的 schema,再扩展到视频、评论或字幕。准备好之后:

• 领取 SandBase API key
• 浏览 YouTube 端点
• 打开 channel-id 的 API 参考