YOUTUBE TRANSCRIPT API · 指南

怎样在 Python 中使用 youtube-transcript-api?为什么它在我的服务器上会失败?

youtube-transcript-api 是一个免费的开源 Python 库:用 pip 安装,然后用视频 ID 调用 fetch() 即可。它在你自己的电脑上运行良好,但在云服务器上经常被 YouTube 屏蔽。2026 年 11 月 21 日我们在云服务器上运行,两个视频都报了 IpBlocked。

更新于 2026年11月21日 · 阅读约 3 分钟

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 版,请求了两节公开课:

youtube-transcript-api 在云服务器上报 IpBlocked,而同一台机器通过 YouTubeTranscript.dev 的 API 拿到了同样两个视频同一台机器,同样两个视频,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:404.2 秒3,3572861
1. What is Computation? (MIT OpenCourseWare)43:064.2 秒6,3638871
同一个 3Blue1Brown 视频,再次请求18:401.3 秒3,3572860

测量方法: 每个视频向 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,都可以按同样的方式来:

  1. 把密钥放在服务器上。 用户把链接发到你的后端,由后端调用 API。不要把密钥放进浏览器或应用的代码里。
  2. 接受任何链接格式。 按用户输入的原样传递链接;我们的 API 接受完整 URL、youtu.be、Shorts、嵌入链接和单独的 ID(完整列表)。
  3. 按视频 ID 保存文稿。 大多数产品会反复请求同样的热门视频。在我们这里,账号已有的文稿再次获取不收费,如上表第三行所示,但本地副本更快。
  4. 把没有字幕的视频当作任务处理。 转写音频的耗时超过一个网页请求应等待的时间。发送 mode: "auto" 并附上 webhook_url,或轮询返回的任务 ID,同时向用户展示进度。
  5. 数量多时使用批量。 对于播放列表、频道或积压任务,使用批量接口而不是循环单次调用,以免超出速率限制。

每个字段都在 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 的异步任务处理,大量视频则使用批量接口。

继续阅读

立即开始免费提取文本

数秒でYouTubeの動画をテキストに変換します。クレジットカードは必要ありません。

YOUTUBETRANSCRIPT.DEVをお試しください →
youtube-transcript-api(Python):用法与失败原因 | Creator Research