YouTube 评论分析 API 教程:从一条视频读懂观众反应 | SandBase
用 Python 独立读取视频信息或一页 YouTube 评论,校验视频 ID 与响应结构,保留原始计数,区分回复 token 和历史实验。

拿到一页评论,已经可以回答一个具体问题:这批返回的评论在讨论什么。它不能代表所有观看者的态度。先确定一个视频,选定排序方式,保存一次响应,再判断是否有必要继续。若你还需要核对视频身份、作者和上下文,视频信息查询是另一个可以单独选择的任务。
这次 2026-11-08 修订把接入收敛为两个独立首请求。依据来自当前免费 inspect 和公开参考资料,没有执行新的业务调用、续页、楼中楼展开或情感模型调用。原文 2026-10-01 UTC 的实验片段保留在历史章节,10 月 7 日保存的公开样本另行注明日期;旧的多步 Python 已精确归档,不再作为当前默认流程。
先说结论
- 已知视频 ID 后,选择视频信息或一页顶层评论,示例不会自动执行两项任务。
- 只读取 documented outputs[0].data;缺少响应结构应报错,有效的空 comments 数组则是另一种结果。
- 20 条只是样本页长度,不能当成固定页容量;top 也不是按点赞降序或代表全体观众的抽样。
- 原样保留计数字符串和空值,区分列表续页 token 与楼中楼 token。本轮验证的是离线解析,不是新的线上续页。
沿用封面是概念插画。评论/回复卡片和多步 agent 链路属于示意,不代表新测量或本轮自动执行了评论分析。
先选一个读者问题
| 你要回答的问题 | 当前端点 | 首次请求 |
|---|---|---|
| 这是不是我准备研究的视频? | Video Info | video_id、language_code en、need_format true |
| 一页可见讨论在说什么? | Video Comments | 同一视频与格式,country_code US,sort_by top 或 newest,省略 continuation_token |
这两个端点使用 SandBase key 读取公开数据,不发布回复、不管理频道,也不提供账号授权内容的访问权。YouTube API 导航 介绍更广的目录;如果问题是“视频说了什么”,应看字幕流程教程,而不是把评论当成视频正文。
原文保留的历史 YouTube 目录截图。API Free Week 免费标识、33 个端点和目录 GET 路径不是当前价格或可用性证明;本例使用带厂商路径的 POST Model API。
把任务交给已连接的 agent
已有 key 的用户直接复用环境变量或密钥管理器里的 SANDBASE_API_KEY。已经连接的 agent 只需拿到选定视频 ID 和任务,不必重新开户,也不要把 key 粘贴到聊天里。新项目可以一起提供 setup Skill、Markdown quickstart 和具体 API 页面;账号准备步骤见快速入门。
可以这样描述任务:“为这个视频读取一页顶层评论,使用 top 排序和英文/美国显示偏好。保留原始值,拿到一次响应就停止;请求或结构不符合预期时明确告诉我。”如果你需要的只是视频信息,就选 info,不要顺带抓评论。这样预算和后续分析范围会在追加调用前保持清楚。
在项目环境安装 requests。下方是一个完整的单次脚本。它要求传入视频 ID,不从任意 URL 里猜提取结果。当前 schema 明确约束字符串长度为 11;代码另外采用常见 ASCII 视频 ID 字符集做本地防错,这不是对上游新增参数的宣称。
import os
import re
import requests
API = "https://api.sandbase.ai/v1/api/youtube/web-v2"
def first_request(task, video_id, sort_by="top"):
if task not in ("info", "comments"):
raise ValueError("Choose info or comments")
if not isinstance(video_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
raise ValueError("Provide one 11-character video ID, not a URL")
if sort_by not in ("top", "newest"):
raise ValueError("Choose top or newest")
payload = {"video_id": video_id, "language_code": "en", "need_format": True}
route = "video-info"
if task == "comments":
route = "video-comments"
payload.update({"sort_by": sort_by, "country_code": "US"})
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY in your environment")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=payload, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network request failed; inspect locally before another call") from None
except ValueError:
raise RuntimeError("SandBase returned invalid JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
data = outputs[0].get("data")
if not isinstance(data, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if task == "info":
if data.get("video_id") != video_id or not isinstance(data.get("title"), str):
raise RuntimeError("Video reference shape or selected ID does not match")
else:
comments = data.get("comments")
if not isinstance(comments, list) or any(not isinstance(c, dict) for c in comments):
raise RuntimeError("Missing comments array of objects")
return data
if __name__ == "__main__":
result = first_request("comments", "dQw4w9WgXcQ")
print("Received fields:", sorted(result))若改查视频信息,把主程序赋值替换为 result = first_request("info", "dQw4w9WgXcQ")。若改看最新评论,使用 result = first_request("comments", "dQw4w9WgXcQ", "newest")。应替换赋值行,不要在后面追加调用。代码不自动重试、不跟随重定向、不续页,也不访问媒体。错误消息不会回显 key、请求头或上游完整响应。
这里的业务结构检查以现有简化参考为依据,遇到结构变化会停止,不假设字段永远不变。视频信息中的返回 ID 必须和选择的视频一致,才交给调用方保存。评论对象则保持原样,让可选字段、缺失计数和 token 留待明确的后续需求处理。
当前保存样本能证明什么
公开保存的 Video Info 样本 ID 为 0db08ecb-a998-4c0c-bdb4-1a0057e0cb39,created_at 是 2026-10-07T17:37:11.533Z;Video Comments 样本是 47d6201e-7702-4398-a94a-4f7b9b722ddf,时间为 2026-10-07T17:37:18.832Z。两者 input_snapshot 都只含 dQw4w9WgXcQ 的 video_id。它们提供参考结构,并不是刚用本文明确指定的英文参数重新执行过。
视频信息直接位于业务对象中,包含 video_id、title 和可用的作者、频道及计数字段。captions 中的轨道引用不等于已经下载的字幕正文。缩略图、片尾链接和国家列表只是数据,不会触发播放或抓取。样本中的 playability_status 为 OK,也不能推导出视频下载或转载权限。
保存的评论响应含 comments 数组与页级 continuation_token,实际有 20 条。当前选中 schema 没有 page_size,也没有数字 offset。不要用显示的 comment_count 除以 20 计算“完整抓取需要几次”:顶层评论与回复的统计范围不同,单次观察也不能保证每页长度一致。
纯数字字符串、缩写计数和未知值要分开处理。short_view_count 为空不是零;相对时间不是精确发布时间。language_code 设置的是显示偏好,不保证把用户写的评论翻译成对应语言。代码明确使用英文,而 schema 默认是 zh-CN。之后若把样本保存到数据库,应另记抓取时间,不把“一个月前”回填为某个确定日期。
历史 Video Info 参数参考,展示 video_id、language_code 和 need_format。旧空示例不是本轮新响应;10 月 7 日保存的参考已在上文单独标注。
两类 token 不要混用
响应顶层的 continuation_token 用于顶层评论列表续页。某条评论内的 reply_continuation_token 属于那条楼中楼,需要作为 continuation_token 交给单独的 Video Comment Replies 端点。将来若设计续页状态,应同时保留视频 ID 与父评论身份,不能跨视频混用,也不能把 comment_id 当作 token。
当前文档描述了这些参数,但本轮没有执行续页往返。新 helper 省略 token,拿到第一页就停。后续如果确实需要更多页,应保留原视频、排序与语言地区,单独核对预算和真实响应。不要复用文章中截断的 token,也不要因为某次返回空 token 就宣称整个线程已完整读取。
top 采用提供方排序,不是已文档化的严格点赞降序。newest 提供另一种样本,也不直接等于“自上次抓取以来的全部新增评论”。缺失和缩写的点赞数无法无损转成精确排名。研究记录应注明视频、排序、语言地区以及实际返回条数,主题总结只描述采集到的评论,不扩展成全体观众结论。
历史 Video Comments 参考,包含 country_code、language_code、need_format、sort_by 和 continuation_token,没有可配置页容量。本轮没有执行续页。
保留原 10 月 1 日实验
以下 JSON 和 run ID 来自 2026-10-01 原实验。Pixel 视频标题和数值按原记录保留,没有在 11 月 8 日复测。六次调用的研究流水线属于历史实验,不是上方首请求脚本的行为。
原实验使用公开 Pixel 视频 GNuXueQ1BYc。Video Info 调用 7cdb6ca7-c07e-40c6-bc60-737cfb399591 与重复调用 a8bbc61e-d8d3-4d45-9167-dbce8db97779 记录了下面的裁剪片段:
{
"title": "Google Pixel 11 Pro | Meet 11",
"author": "Made by Google",
"channel_id": "UCIG1k8umaCIIrujZPzZPIMA",
"channel_handle": "@madebygoogle",
"publish_date": "2026-08-10T09:18:13-07:00",
"view_count": "394650",
"like_count": "7009",
"comment_count": "600",
"category": "Science & Technology",
"is_unlisted": false,
"playability_status": "OK"
}另一个 OpenAI 直播样本 4659dbe8-0c6e-4cbb-a7af-8c4f44eb42b9 的 comment_count 为 null;ca8e3dd0-cbd7-4210-a14a-2805603a3bec 返回空评论和空 token。这不能确认是关闭评论还是上游没有返回。
Pixel 评论调用 6a15e813-0975-424e-a08a-07975dc706d5 返回 20 条;以下原始片段省略作者对象:
{
"comment_id": "UgyqM6dj...",
"content": "If only the tensor was half as good as this marketing.",
"like_count": "157",
"like_count_a11y": "157 likes",
"published_time": "1 month ago",
"reply_count": "2",
"reply_count_text": "2 replies",
"reply_continuation_token": "Eg0SC0dOdVh1ZVExQlljGAYy...",
"reply_level": 0
}另一个视频的第二页 21210ef3-0cdd-4ad9-9ad3-9e28a55155d1 当时返回 20 条,和上一页没有 ID 重叠,只能说明那两页。c12ba06d-d2ae-420f-bd99-d72b40069013 观察到“32万”“1年前”等本地化字符串;top 页面 82cafd48-fc3a-480c-ae50-03864d83d026 将近期 17 赞评论与更早的大计数评论混排,不能理解为点赞降序。
显示 36 条回复的旧线程第一次只返回 8 条且简化 token 为 null(249fe9fe-4f7a-4ef9-b50e-90da4a17ff11),加 country US 重试仍相同(d965b8af-9927-4708-8f13-4e8632841cb6)。未格式化响应 f50e9fe6-96bc-42a3-8571-2af0e2c91c4c 含另一个 token,随后 d1c96510-5c14-41a3-a094-31fc801721b7 得到 28 条。历史 8+28 恰好对应显示的 36,不等于当前原始 token 算法已通过验证。
原端到端实验共记录六次调用:信息 f2fd60da-9f2e-4bd7-a9ec-b3c5e381df31;评论页 807d5158-e110-47db-b790-8ba9ff74464c、274438ca-9c43-466d-b44b-d4293d997537;回复样本 1299f8fc-c2a6-4b13-9c93-8d44573909c8、9b827f63-e3b1-45fc-baf6-2564f12fe5e7、3e086713-c5e7-4315-9c1a-ebc059c72cab。当时读取显示 600 条评论中的 40 条顶层评论,对显示 36/6/4 回复的线程采集到 8/6/4 条,并找到 6 条含问号的评论。原作者归纳的配乐好评、Tensor 质疑、电池关注和升级问题只是对小样本的阅读,不是受众比例测量。
历史楼中楼实验说明,显示的回复数和简化响应中的空 token 不能单独证明完整性;它不构成继续递归搜索任意原始 JSON token 的现行推荐方案。包含重试、计数转换、分页和回复选择的旧代码已逐字保存到历史 Python 归档,当前接入使用上方单次 helper。
历史 Video Comment Replies 参数参考。本轮未重新验证或执行楼中楼展开,也未使用旧原始 token 回退算法。
费用与下一步判断
2026-11-08 免费 inspect 显示,两个选中端点各为 0.001 美元/次,具备组织内共享的每日 100 次合资格数据 API 额度,UTC 00:00 重置。具备资格不等于查询过剩余额度、账户余额或实际扣费,也不保证免费成功。一个选定请求的额度抵扣前价格是 0.001 美元,独立选择两项是 0.002 美元;执行前仍要核对现价与账户情况。
一次响应之后,先判断它是否解决了原问题。新品复盘中,小样本可能提示值得追问的问题,但不能量化问题普遍程度。支持文档研究应阅读具体文本,不能只按问号统计真实工单需求。赞助评估中,一页 top 评论也不能证明互动真实性或整体受众质量。这些是拿到数据后的解释工作,不是自动追加 API 调用的理由。
有效的空 comments 数组应如实报告。原实验中“空计数配合空评论”的组合没有确认评论是否被关闭、删除或在其他界面不可见。失败请求和有效空页还应分别记录:二者需要的后续动作不同,不应统一写成“没有评论”。只有额外调用能解决明确的不确定性时,再决定是否继续。
常见问题
视频信息里有完整字幕吗? 字幕轨道引用不是字幕正文。选择轨道和读取文本是另一个任务,需要相应端点和响应检查。
一次能拿到全部评论吗? 参考样本不支持完整性保证。20 条是观察到的页长度,不是固定容量;当前示例读取一页后停止。
top 就是点赞最多吗? 没有严格按点赞降序的文档保证。应注明提供方排序,保留原始计数,不把未知值改成零。
HTTP 503 要自动重试吗? 本例停止并报错。历史某次重试成功,不足以证明当前所有任务都适合自动重试或无需另算费用。
需要 YouTube OAuth 吗? 本文公开读取使用 SandBase key;账号授权操作不在教程范围内。
总结
已知视频 ID 后,先选视频信息或一页评论。检查 documented 信封与所选参考结构,保留未知值,在追加页数或展开回复前停下来判断任务。下一步从 Video Info、Video Comments 或 YouTube API 导航 进入。
2026 年 SandBase YouTube 枢纽的标价,见 2026 年最佳 YouTube API:价格对比。
觉得有用?分享给更多人