如何用 API 获取 YouTube 文字稿(curl、Python、JavaScript)

要用 API 获取 YouTube 文字稿,只需带上视频 URL 或 ID 和一个 API 密钥发送一次 HTTP 请求,再从响应中读取文字稿。本指南使用 sum.video 文字稿 API,用 curl、Python 和 JavaScript 演示请求,然后介绍格式、错误和费用。

API 会返回什么

该接口返回公开 YouTube 视频的现有字幕,无论是创作者撰写的,还是 YouTube 自动生成的。它不会对音频做转写。如果视频没有字幕,你会得到一个错误,而不是猜测的结果(详见下文)。

基本信息:

• 接口:POST https://sum.video/api/v1/transcript(GET 也可以)
• 认证:把密钥放在 X-API-Key 请求头中,或使用 Authorization: Bearer <key>
• 输入:url 或 video_id
• 可选的 lang(默认 en)
• 可选的 format:json、text 或 srt

响应还会告诉你字幕轨道的真实语言以及它是否为自动生成,这样你就知道该期待怎样的质量。

第 1 步:创建 API 密钥

登录后,在 API 控制台(sum.video 上的 /dashboard/api)创建密钥。你最多可以有 5 个有效密钥,方便把测试密钥和正式密钥分开。第一个密钥附带 10 个免费积分,足够 5 份文字稿,所以下面的内容都可以免费试用。

第 2 步:发送第一个请求

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

因为 GET 也可用,你也可以用只拼接 URL 的脚本来测试。密钥最好放在请求头里,这样不会出现在日志中。

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript(Node 18+ 或浏览器)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

请把密钥放在服务器上。放在浏览器代码里的密钥,任何打开开发者工具的人都能复制。

第 3 步:选择合适的格式

如果打算链接到视频中的某个时刻,请使用 json,并根据分段的 offset 生成链接。要喂给大模型,text 更小也更简单。如果之后想手动在文字稿里搜索,请看如何在 YouTube 视频的文字稿中搜索。

第 4 步:选择语言

lang 默认是 en。把它设为你想要的语言,例如 de 或 es。响应会报告实际返回的轨道语言,所以请核对,不要想当然。视频往往只有一条字幕轨道,而 API 返回的是真实字幕,因此不会替你翻译。

第 5 步:处理错误

从第一天起就要考虑这些情况:

• 404 no_transcript:视频没有字幕,或者是直播、私享视频或已删除的视频。重试没有意义。跳过它,或请用户提供另一个视频。
• 402 budget_exceeded:你达到了所设置的月度积分上限。见下一节。
• 速率限制:每个密钥每分钟允许 60 次请求。批量任务要错开,被限流时就放慢速度。
• 我们这一侧的故障:稍等片刻后重试。这类请求不收费。

一个简单的循环,遇到服务器错误就重试、遇到 404 就跳过,就能满足大部分生产需求。

费用

每份文字稿消耗 2 个积分。没有返回文字稿的请求,或在 sum.video 一侧失败的请求,不收费,所以 404 永远不会消耗你的余额。你可以用 GET /api/v1/credits 查看余额。

积分以一次性套餐出售,永不过期:

Pro 订阅用户每月还会获得 100 个赠送积分。对于更重的工作负载,比如导入整个频道,请阅读场景文章面向大规模 RAG 应用的 YouTube 文字稿,其中讲到了自动充值和预算。另见价格。

开发前需要了解的限制

• 只有带字幕的视频才能使用。这是 404 no_transcript 的主要原因。
• 自动生成的字幕可能有错误,尤其是人名、口音和专业术语。
• API 只返回文字稿,不做摘要。如果你想在文字稿之上获得摘要、时间戳和对话,YouTube 摘要工具可以做到,而文字稿工具则是针对单个视频的免代码版本。
• 官方的 YouTube Data API 在这里无法替代。它的字幕下载方法需要有编辑该视频的权限,因此只适用于你自己的视频(Google 文档)。

来源

• YouTube Data API: Captions.download
• sum.video 文字稿 API