用 YouTube Data API 获取转录文本：为什么 captions.download 会失败

终端显示 YouTube Data API captions.download 端点返回 403 Forbidden

如果你正在尝试通过 YouTube Data API 获取转录文本，多半已经撞上了这堵墙：captions.list 对任何视频都会痛快地返回字幕轨 ID，但你一对其中某条调用 captions.download，就会收到 403。你反复检查 API 密钥、加上 youtube.force-ssl 权限范围、试了 OAuth——还是 403。这不是 bug，也不是配额问题。这是有意设计的，而文档把重点埋得很深。

这条限制，说得精确一点

captions.download 要求 OAuth 令牌来自拥有该视频的账号。不是随便哪个已认证账号——必须是频道所有者（或对该视频有权限的内容管理者）。字幕相关端点的存在，是为了让创作者管理自己上传视频的字幕轨：上传 .srt、改个错别字、删掉糟糕的自动翻译。下载任意第三方视频的字幕从来就不在契约之内。

只要仔细读，错误信息其实说得很明白：

The permissions associated with the request are not sufficient
to download the caption track.

所以常规的升级路线——API 密钥 → 以自己身份 OAuth → 更大的权限范围 → 服务账号——全都走不通。每一级都会栽在同一个所有权检查上。我在这上面耗掉了一下午才接受现实，而从 Stack Overflow 的相关流量看，半个互联网都栽过。

captions.list 仍然有用的地方

给 Data API 说句公道话：captions.list 用普通 API 密钥就能工作，消耗约 50 个配额单位。它能告诉你存在哪些字幕轨、语言是什么，以及是自动生成（trackKind: "asr"）还是人工上传。作为预检这确实有用——如果一个视频完全没有字幕轨，你就提前知道要用语音转文字而不是提取字幕。Data API 依然是搜索、播放列表枚举和元数据的正确工具。它只是不会把转录文本交给你。

方案一：像播放器那样获取字幕

视频播放器显然无需所有者的 OAuth 令牌就能收到字幕数据，youtube-transcript-api（Python）这类库就是用同样的方式获取的。在你的笔记本上这很好用，三行代码搞定。

问题出在生产环境：YouTube 会激进地质询来自数据中心 IP 段的请求。把同样三行代码部署到 AWS、GCP 或 Heroku，你就会开始看到 "Sign in to confirm you're not a bot" 和 IpBlocked 错误。我在为什么 youtube-transcript-api 在云端会被封锁里单独写了这种失败模式和应对方案——一句话版本：用住宅代理可以解决，但那本身就是一个工程。

方案二：托管的转录文本 API

如果你只想从一个 URL 拿到文本，托管端点能同时绕开这两个问题——没有所有权要求，也不用伺候代理。youtube2text.org 在服务端用轮换住宅代理来抓取字幕，你的请求从哪里发出都无所谓：

# grab a free demo key (shared, 5 videos/month per IP)
curl -s https://youtube2text.org/api/demo-key

# fetch a transcript
curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -H "x-api-key: yt_YOUR_KEY"

响应是普通的 JSON：

{"result": {"videoId": "...", "title": "...", "pubDate": "...",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

如果视频确实没有字幕，你会收到带 404 的 TRANSCRIPT_UNAVAILABLE——这与 captions.list 返回空字幕轨列表是同一种情况，只不过一次调用就能查明，而不用两次。

带错误处理的更长教程见用 curl 提取 YouTube 转录文本；如果你更习惯基于 requests 的代码，youtube-transcript-api 迁移指南里有 Python 版本。

一套理智的组合方案

两头都踩过坑之后，今天我实际会这样搭：

Data API 负责发现——搜索、频道上传、播放列表、发布日期。它在元数据方面可靠且配额慷慨。
一个转录文本端点（托管的，或者你乐在其中的话，自己配代理抓取）负责真正的文本。
语音转文字作为兜底，只用于完全没有字幕的视频。

硬要让 captions.download 承担中间那份工作，是唯一一条对你不拥有的视频绝无可能走通的路——换权限范围、换密钥、改控制台设置都改变不了这一点。

如果你想要自己的密钥而不是共享演示密钥，在 youtube2text.org/app/keys 用 Google 登录即可——不要手机号，不要银行卡。免费档每月 5 个视频；付费套餐从 $5.99 的 50 个起。