HomeBlogTranscribePlansAPI Keys

Python 中的 YouTube 转录文本 API：10 行 requests 代码

Python 脚本使用 requests 库将 YouTube 转录文本作为 JSON 获取

youtube_transcript_api._errors.IpBlocked:
Could not retrieve a transcript for the video.
YouTube is blocking requests from your IP.

如果那个回溯把你带到这里，欢迎。这是流行 pip 包的标准失败模式，一旦你的代码离开笔记本电脑并登陆 AWS、GCP 或任何其他数据中心 IP。本文介绍了另一条路线：一个托管的 YouTube 转录文本 API，你可以从 Python 用 requests 调用。到最后，你将有一个十行脚本，可以将任何 YouTube URL 转换为转录文本，加上速率限制和没有字幕视频的正确处理。

为什么 pip 库在生产环境中失败

youtube-transcript-api 直接从运行它的任何机器爬取 YouTube。本地没问题。部署它，YouTube 的机器人检测会在几天内（有时几分钟内）标记你的云提供商的 IP 范围。我在为什么 YouTube 转录文本 API 被阻止中写了详细细节——简版：你最后租赁住宅代理来读取公开字幕，这是荒谬的。

youtube2text.org 在服务器端做面向 YouTube 的部分。你的代码发送一个 HTTPS 调用并获取 JSON 返回。

十行代码

无需账户就能尝试——有一个演示密钥端点：

import requests

API = "https://youtube2text.org/api/transcribe"
KEY = requests.get("https://youtube2text.org/api/demo-key").json()["apiKey"]

resp = requests.get(API, params={"url": "https://youtu.be/dQw4w9WgXcQ"},
                    headers={"x-api-key": KEY}, timeout=60)
resp.raise_for_status()
result = resp.json()["result"]
print(result["title"])
print(result["content"][:300])

url 参数接受任何 YouTube URL 形式——watch?v=、youtu.be、shorts、embeds——或裸露的 11 字符视频 id。响应给你 videoId、title、pubDate、content、contentSize 和一个 truncated 标志。

关于那个演示密钥的一个警告：它跨所有人共享，每个 IP 每月限制 5 个视频。对于试用来说不错，对任何真实用途都无用。

像成年人一样处理 429 和 404

raise_for_status() 对演示来说不错，但错误作为结构化 JSON 返回，带有一个你可以分支处理的 code：

import time

resp = requests.get(API, params={"url": video_url},
                    headers={"x-api-key": KEY}, timeout=60)
body = resp.json()

if resp.status_code == 200:
    transcript = body["result"]["content"]
elif resp.status_code == 429:
    time.sleep(body["error"]["retryAfterSeconds"])  # then retry
elif resp.status_code == 404:
    if body["error"]["code"] == "TRANSCRIPT_UNAVAILABLE":
        transcript = None  # video exists, but has no captions — skip it
    else:
        raise ValueError(f"No such video: {video_url}")  # VIDEO_NOT_FOUND
else:
    raise RuntimeError(body["error"]["message"])

TRANSCRIPT_UNAVAILABLE 值得诚实地讨论一下：转录文本来自 YouTube 的字幕轨道（手动或自动生成），有些视频根本没有。没有 API 能凭空变出不存在的文本——对于那些，你需要真正的语音转文本，我在Whisper vs YouTube 字幕中进行了比较。重试也不会有帮助，所以别试。

maxChars 和 LLM 令牌预算

如果转录文本要进入提示，你关心大小。一个三小时的播客转录文本会毫不犹豫地消耗 100k 个令牌。maxChars 参数限制输出——默认和最大都是 150000：

resp = requests.get(API,
    params={"url": video_url, "maxChars": 20000},
    headers={"x-api-key": KEY}, timeout=60)

按粗略的每令牌 4 字符规则，maxChars=20000 大约落在 5k 令牌。检查 result["truncated"] 以了解你是否得到了整个东西。如果你把这个接入检索管道而不是单一提示，LangChain 集成文章涵盖了正确的分块。

离开演示密钥

当每月 5 个共享视频不再足够时，在 youtube2text.org/app/keys 用 Google 登录并创建你自己的密钥——无需电话号码、无需信用卡。免费层是每个密钥每月 5 个视频；付费层从 50 个视频 5.99 美元起。上面的十行代码不改变，只有标题中的字符串改变。