youtube-transcript-api 是一个免费的开源 Python 库,用来获取 YouTube 视频的字幕:先 pip install youtube-transcript-api,再调用 YouTubeTranscriptApi().fetch(video_id)。在你自己的电脑上它运行良好,但从云服务器上运行时,YouTube 经常用 RequestBlocked 或 IpBlocked 把它挡住,而且它对没有字幕的视频无能为力。
2026 年 11 月 21 日,我们在一台云服务器上运行了它,然后在同一台机器上把同样两个视频交给我们自己的托管 API。下面是各自的结果、这个库的用法,以及什么时候更适合用托管 API。
youtube-transcript-api 是什么?
它是 Jonas Depoix 开发的 Python 库,发布在 GitHub 和 PyPI 上,采用 MIT 许可。撰写本文时的最新版本是 1.2.5,支持 Python 3.8 及以上。
- 它读取 YouTube 上已有的字幕,可以是频道自己的字幕,也可以是 YouTube 的自动字幕。
- 不需要 API 密钥,也不需要无头浏览器。
- 可以列出视频的字幕语言、指定优先语言,并使用 YouTube 的机器翻译。
- 可以输出文本、JSON、SRT 或 WebVTT,还有命令行工具。
它的 README 坦率说明了取舍:它使用的是 YouTube 网页播放器中未公开的部分,因此“no guarantee that it won't stop working tomorrow”。
怎么用?
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
在命令行中,youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json 可以做同样的事。语言列表、翻译等更多用法见 README。
为什么它在我的服务器上报 IpBlocked?
因为 YouTube 会屏蔽大多数来自云服务商的请求。这个库的 README 写得很清楚:YouTube “has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)”,所以代码部署后你“most likely”会遇到 RequestBlocked 或 IpBlocked 错误。家用 IP 在请求过多后也可能被屏蔽。
我们亲眼看到了。2026 年 11 月 21 日,我们在一台云服务器上安装了 1.2.5 版,请求了两节公开课:
同一台机器,同样两个视频,2026 年 11 月 21 日(UTC)。
两次调用都在约 1.1 秒后报了 IpBlocked。从这台机器直接访问 youtube.com,会被重定向到 Google 的“异常流量”页面,所以是 YouTube 拒绝了这台机器,而不是库的问题。
README 给出的办法是使用代理,并推荐轮换的住宅代理,因为固定代理用久了会被 YouTube 封禁。这能解决问题,但意味着多一项付费服务、多一个账号,还要持续关注封禁。
还有什么会让它失败?
- 没有字幕。 这个库读取字幕,不转写音频。字幕关闭会报
TranscriptsDisabled,缺少语言会报NoTranscriptFound。 - 有年龄限制的视频。 README 说,这类视频需要的 Cookie 登录在 YouTube 端改动后“currently not available”。
- YouTube 的变动。 由于使用的是未公开接口,YouTube 一次更新就可能让它失效,直到新版本发布。
这些都不妨碍你在笔记本上跑脚本时使用它,但在放进产品之前应该提前规划。
被屏蔽时可以用什么替代?
一个在自己这边完成抓取的托管文稿 API。我们的是 YouTubeTranscript.dev 的 API。在同一台云服务器上、几分钟之前,同样两个视频的结果:
| 视频 | 时长 | 用时 | 词数 | 带时间戳的行 | 积分 |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4.2 秒 | 3,357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4.2 秒 | 6,363 | 887 | 1 |
| 同一个 3Blue1Brown 视频,再次请求 | 18:40 | 1.3 秒 | 3,357 | 286 | 0 |
测量方法: 每个视频向 POST /api/v2/transcribe 发送一次请求,只取字幕并开启时间戳,用 curl 从发送计时到收到完整响应。积分是每次响应报告的数值。每个只测一次,所以用时仅供参考。
在 Python 中调用:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
取舍在于费用:这个库免费,而 API 每个有字幕的视频收 1 个积分,每月有 10 个免费积分,付费套餐 5 美元起含 500 个积分。使用 "mode": "auto" 时,它还能转写没有字幕的视频,每 2 分钟音频 1 个积分。如果不想自己写请求,可以用 Python SDK。
怎样把转写 API 集成到我的产品里?
无论用哪个 API,都可以按同样的方式来:
- 把密钥放在服务器上。 用户把链接发到你的后端,由后端调用 API。不要把密钥放进浏览器或应用的代码里。
- 接受任何链接格式。 按用户输入的原样传递链接;我们的 API 接受完整 URL、youtu.be、Shorts、嵌入链接和单独的 ID(完整列表)。
- 按视频 ID 保存文稿。 大多数产品会反复请求同样的热门视频。在我们这里,账号已有的文稿再次获取不收费,如上表第三行所示,但本地副本更快。
- 把没有字幕的视频当作任务处理。 转写音频的耗时超过一个网页请求应等待的时间。发送
mode: "auto"并附上webhook_url,或轮询返回的任务 ID,同时向用户展示进度。 - 数量多时使用批量。 对于播放列表、频道或积压任务,使用批量接口而不是循环单次调用,以免超出速率限制。
每个字段都在 API 文档 中,而我们的 语音转文字 API 指南 测量了无字幕音频的准确率和成本。
我该用哪个?
| 如果你在… | 使用 |
|---|---|
| 在自己的电脑上跑脚本,一次几个视频 | youtube-transcript-api |
| 部署到云服务器、Serverless 函数或产品中 | 托管 API,或者这个库加轮换住宅代理 |
| 处理没有字幕的视频 | 能转写音频的服务 |
| 获取整个播放列表或频道 | 带批量接口的托管 API |
总结
- youtube-transcript-api 免费、MIT 许可、用法简单:
YouTubeTranscriptApi().fetch(video_id)。 - 在云服务器上 它经常被 YouTube 屏蔽;在我们的云服务器上,两个视频都在约 1.1 秒后报了
IpBlocked。建议的解决办法是代理。 - 它只能读取已有字幕,有年龄限制的视频目前也无法获取。
- 托管 API 在同一台机器上返回同样的视频各用 4.2 秒、各 1 个积分,也能处理没有字幕的视频。
常见问题
youtube-transcript-api 是什么?+
一个开源 Python 库(MIT 许可),无需 API 密钥和浏览器,就能获取 YouTube 上视频已有的字幕,包括自动字幕。用 pip install youtube-transcript-api 安装,用 YouTubeTranscriptApi().fetch(video_id) 调用。
youtube-transcript-api 为什么会报 RequestBlocked 或 IpBlocked?+
因为 YouTube 会屏蔽大多数来自云服务商 IP 地址的请求,也可能屏蔽请求过多的任何 IP。这个库的 README 自己就这么写,并建议使用轮换的住宅代理。2026 年 11 月 21 日在我们的云服务器上,测试的两个视频都在约 1.1 秒后报了 IpBlocked。
youtube-transcript-api 能转写没有字幕的视频吗?+
不能。它只读取已有的字幕。字幕被关闭的视频会报 TranscriptsDisabled,没有你要的语言会报 NoTranscriptFound。要从音频得到文字,需要语音转文字服务。
youtube-transcript-api 免费吗?+
是的,这个库免费并采用 MIT 许可。但在服务器上使用通常需要付费购买代理,因为云 IP 会被屏蔽。
在服务器上可以用什么替代 youtube-transcript-api?+
一个替你完成抓取的托管文稿 API。在这个库被屏蔽的同一台机器上,YouTubeTranscript.dev 的 API 返回两个视频各用 4.2 秒、各 1 个积分,重复请求用时 1.3 秒且免费。
怎样把转写 API 集成到我的产品里?+
把 API 密钥放在服务器上,把视频链接发到一个接口,按视频 ID 保存文稿以免重复付费,把没有字幕的视频当作带 Webhook 的异步任务处理,大量视频则使用批量接口。