youtube-transcript-api

YouTube Transcript API 技能

当用户想要提取 YouTube 视频字幕、为没有字幕的视频转录、翻译视频内容或批量处理多个视频时，使用此技能。

适用场景

• 用户要求获取 YouTube 视频的转录文本／字幕
• 用户想要转录没有字幕的 YouTube 视频（ASR）
• 用户想要将 YouTube 视频转录文本翻译成其他语言
• 用户需要一次处理多个 YouTube 视频
• 用户想要构建使用 YouTube 视频内容的 AI/大模型流水线
• 用户想要将视频内容转换成文本（博客文章、摘要等）

API 概览

基础 URL： https://youtubetranscript.dev/api/v2

身份验证： 通过 Authorization: Bearer YOUR_API_KEY 使用 Bearer 令牌

用户可以在 youtubetranscript.dev 免费获取 API 密钥。

端点

方法	端点	描述
POST	/api/v2/transcribe	提取单个视频的转录文本
POST	/api/v2/batch	提取最多 100 个视频的转录文本
GET	/api/v2/jobs/{job_id}	查看 ASR 作业状态
GET	/api/v2/batch/{batch_id}	查看批量请求状态

请求字段

字段	必填	描述
video	是（单个视频）	YouTube URL 或 11 个字符的视频 ID
video_ids	是（批量）	ID 或 URL 数组（最多 100 个）
language	否	ISO 639-1 代码（例如，"es"、"fr"）。省略则使用最佳可用版本
source	否	auto（默认）、manual 或 asr
format	否	timestamp、paragraphs 或 words
webhook_url	否	用于异步交付的 URL（source="asr" 时必填）

积分费用

方法	费用	速度
原生字幕	1 积分	5–10 秒
翻译	每 2,500 个字符 1 积分	5–10 秒
ASR（音频）	每 90 秒 1 积分	2–20 分钟（异步）

示例

基本转录文本提取（Python）

import requests

API_KEY = "your_api_key"

response = requests.post(
    "https://youtubetranscript.dev/api/v2/transcribe",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"video": "dQw4w9WgXcQ"}
)

data = response.json()
for segment in data["data"]["transcript"]:
    print(f"[{segment['start']:.1f}s] {segment['text']}")

基本转录文本提取（JavaScript/Node.js）

const response = await fetch("https://youtubetranscript.dev/api/v2/transcribe", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ video: "dQw4w9WgXcQ" }),
});

const { data } = await response.json();
console.log(data.transcript);

使用 Node.js SDK

npm install youtube-audio-transcript-api

import { YouTubeTranscript } from "youtube-audio-transcript-api";

const yt = new YouTubeTranscript({ apiKey: "your_api_key" });

// Simple extraction
const result = await yt.getTranscript("dQw4w9WgXcQ");

// With translation
const translated = await yt.transcribe({
  video: "dQw4w9WgXcQ",
  language: "es",
});

// Batch (up to 100 videos)
const batch = await yt.batch({
  video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw", "9bZkp7q19f0"],
});

基本转录文本提取（cURL）

curl -X POST https://youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video": "dQw4w9WgXcQ"}'

批量处理（最多 100 个视频）

curl -X POST https://youtubetranscript.dev/api/v2/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw", "9bZkp7q19f0"]}'

翻译

添加 "language": "es"（或任何 ISO 639-1 代码）即可获取翻译后的转录文本：

curl -X POST https://youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video": "dQw4w9WgXcQ", "language": "es"}'

ASR 转录（无字幕的视频）

对于没有字幕的视频，使用 ASR 并提供 webhook：

curl -X POST https://youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video": "VIDEO_ID", "source": "asr", "webhook_url": "https://yoursite.com/webhook"}'

此请求会立即返回 status: "processing"。结果准备就绪后会发送到 webhook URL。如果不使用 webhook，请通过 GET /api/v2/jobs/{job_id} 轮询。

错误处理

HTTP 状态	错误代码	描述
400	invalid_request	JSON 无效或缺少必填字段
401	invalid_api_key	缺少或无效的 API 密钥
402	payment_required	积分不足
404	no_captions	没有可用字幕，且未使用 ASR
429	rate_limit_exceeded	请求过多——请检查 Retry-After 标头

重要说明

• 如果用户尚未提供 API 密钥，务必向其索取。可在 youtubetranscript.dev 免费获取密钥。
• 省略 language 参数会返回最佳可用转录文本，不进行翻译（节省积分）。
• ASR 是异步的——务必使用 webhook URL 或轮询作业端点。
• 批量端点同时接受 YouTube URL 和 11 个字符的视频 ID。
• 重新获取已拥有的转录文本不消耗积分。

资源

• 网站
• 完整 API 文档和 OpenAPI 规范
• npm SDK
• 定价