youtube-transcript-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

YouTube Transcript API Skill

YouTube Transcript API 技能文档

Use this skill when the user wants to extract transcripts from YouTube videos, transcribe videos without captions, translate video content, or process multiple videos in batch.

当用户需要从YouTube视频中提取字幕、为无字幕视频转录内容、翻译视频内容或批量处理多个视频时，可使用本技能。

When to Use

适用场景

User asks to get a transcript/subtitles/captions from a YouTube video
User wants to transcribe a YouTube video that has no captions (ASR)
User wants to translate a YouTube video transcript to another language
User needs to process multiple YouTube videos at once
User wants to build an AI/LLM pipeline that uses YouTube video content
User wants to repurpose video content into text (blog posts, summaries, etc.)

用户请求获取YouTube视频的字幕/副标题/标题
用户需要为无字幕的YouTube视频进行转录（ASR）
用户希望将YouTube视频字幕翻译成其他语言
用户需要一次性处理多个YouTube视频
用户希望构建使用YouTube视频内容的AI/LLM流水线
用户希望将视频内容重新利用为文本形式（如博客文章、摘要等）

API Overview

API概述

Base URL:

https://youtubetranscript.dev/api/v2

Authentication: Bearer token via

Authorization: Bearer YOUR_API_KEY

Users can get a free API key at youtubetranscript.dev.

基础URL：

https://youtubetranscript.dev/api/v2

身份验证： 通过

Authorization: Bearer YOUR_API_KEY

使用Bearer令牌

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

Endpoints

端点

Method	Endpoint	Description
`POST`	`/api/v2/transcribe`	Extract transcript from a single video
`POST`	`/api/v2/batch`	Extract transcripts from up to 100 videos
`GET`	`/api/v2/jobs/{job_id}`	Check status of an ASR job
`GET`	`/api/v2/batch/{batch_id}`	Check status of a batch request

方法	端点	描述
`POST`	`/api/v2/transcribe`	提取单个视频的字幕
`POST`	`/api/v2/batch`	提取最多100个视频的字幕
`GET`	`/api/v2/jobs/{job_id}`	检查ASR任务状态
`GET`	`/api/v2/batch/{batch_id}`	检查批量请求状态

Request Fields

请求字段

Field	Required	Description
`video`	Yes (single)	YouTube URL or 11-character video ID
`video_ids`	Yes (batch)	Array of IDs or URLs (up to 100)
`language`	No	ISO 639-1 code (e.g., `"es"` , `"fr"` ). Omit for best available
`source`	No	`auto` (default), `manual` , or `asr`
`format`	No	`timestamp` , `paragraphs` , or `words`
`webhook_url`	No	URL for async delivery (required for `source="asr"` )

字段	是否必填	描述
`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"` 时为必填）

Credit Costs

积分成本

Method	Cost	Speed
Native Captions	1 credit	5–10 seconds
Translation	1 credit per 2,500 chars	5–10 seconds
ASR (Audio)	1 credit per 90 seconds	2–20 minutes (async)

方式	成本	速度
原生字幕	1积分	5–10秒
翻译	每2500字符1积分	5–10秒
ASR（音频）	每90秒1积分	2–20分钟（异步）

Examples

示例

Basic Transcript Extraction (Python)

基础字幕提取（Python）

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']}")

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']}")

Basic Transcript Extraction (JavaScript/Node.js)

基础字幕提取（JavaScript/Node.js）

javascript

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);

javascript

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);

Using the Node.js SDK

使用Node.js SDK

bash

npm install youtube-audio-transcript-api

javascript

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"],
});

bash

npm install youtube-audio-transcript-api

javascript

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

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

// 简单提取
const result = await yt.getTranscript("dQw4w9WgXcQ");

// 带翻译的提取
const translated = await yt.transcribe({
  video: "dQw4w9WgXcQ",
  language: "es",
});

// 批量处理（最多100个视频）
const batch = await yt.batch({
  video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw", "9bZkp7q19f0"],
});

Basic Transcript Extraction (cURL)

基础字幕提取（cURL）

bash

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

bash

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

Batch Processing (up to 100 videos)

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

bash

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"]}'

bash

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"]}'

Translation

翻译功能

Add

"language": "es"

(or any ISO 639-1 code) to get the transcript translated:

bash

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"}'

添加

"language": "es"

（或任何ISO 639-1代码）即可获取翻译后的字幕：

bash

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 Transcription (videos without captions)

ASR转录（无字幕视频）

For videos that don't have captions, use ASR with a webhook:

bash

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"}'

This returns immediately with

status: "processing"

. Results are delivered to the webhook URL when ready. Poll with

GET /api/v2/jobs/{job_id}

if not using webhooks.

对于没有字幕的视频，结合webhook使用ASR：

bash

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}

轮询状态。

Error Handling

错误处理

HTTP Status	Error Code	Description
400	`invalid_request`	Invalid JSON or missing required fields
401	`invalid_api_key`	Missing or invalid API key
402	`payment_required`	Insufficient credits
404	`no_captions`	No captions available and ASR not used
429	`rate_limit_exceeded`	Too many requests — check `Retry-After` header

HTTP状态码	错误代码	描述
400	`invalid_request`	JSON无效或缺少必填字段
401	`invalid_api_key`	API密钥缺失或无效
402	`payment_required`	积分不足
404	`no_captions`	无可用字幕且未使用ASR
429	`rate_limit_exceeded`	请求过于频繁 — 请查看 `Retry-After` 响应头

Important Notes

重要说明

Always ask the user for their API key if they haven't provided one. Free keys are available at youtubetranscript.dev.
Omitting the
```
language
```
parameter returns the best available transcript without translation (saves credits).
ASR is async — always use a webhook URL or poll the jobs endpoint.
Batch endpoint accepts both YouTube URLs and 11-character video IDs.
Re-fetching an already-owned transcript costs 0 credits.

若用户未提供API密钥，务必向其索要。可在youtubetranscript.dev获取免费密钥。
省略
```
language
```
参数将返回最佳可用的原语言字幕，无需翻译（节省积分）。
ASR为异步操作 — 请务必使用webhook URL或轮询任务端点。
批量端点同时支持YouTube URL和11位视频ID。
重新获取已拥有的字幕不消耗积分。

youtube-transcript-api

Original

Translation

YouTube Transcript API Skill

YouTube Transcript API 技能文档

When to Use

适用场景

API Overview

API概述

Endpoints

端点

Request Fields

请求字段

Credit Costs

积分成本

Examples

示例

Basic Transcript Extraction (Python)

基础字幕提取（Python）

Basic Transcript Extraction (JavaScript/Node.js)

基础字幕提取（JavaScript/Node.js）

Using the Node.js SDK

使用Node.js SDK

Basic Transcript Extraction (cURL)

基础字幕提取（cURL）

Batch Processing (up to 100 videos)

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

Translation

翻译功能

ASR Transcription (videos without captions)

ASR转录（无字幕视频）

Error Handling

错误处理

Important Notes

重要说明

Resources

相关资源