YouTube 转录 API
发送一个 YouTube 链接,在同一请求中拿回转录文本:带时间戳的 JSON 片段,或可直接使用的 SRT、VTT 和纯文本。有人工字幕时返回人工字幕,没有时返回自动生成字幕 —— 并附完整语言列表,让你始终清楚拿到的是什么。
转录 API 做什么
YouTube 转录 API 把视频链接变成结构化的字幕数据。Tunelio 的 GET /transcript 端点解析视频,为你请求的语言挑选最佳字幕轨道(优先人工字幕而非自动生成),并返回每个片段及其开始时间和时长 —— 外加拼接好的全文和该视频提供的所有其他语言的目录。无需浏览器自动化、无需 cookies、无需维护 yt-dlp;只需带 API key 的一次 HTTPS 请求。
工作方式
可直接复制的示例
把 tnl_… 替换为控制台中的 API key。同一 key 也适用于 /info 和 /create。
curl -X GET "https://tunelio.dev/transcript?url=dQw4w9WgXcQ&lang=en&format=json" \
-H "Authorization: Bearer tnl_…"const res = await fetch(
"https://tunelio.dev/transcript?" + new URLSearchParams({
url: "dQw4w9WgXcQ",
lang: "en",
format: "json",
}),
{ headers: { Authorization: "Bearer " + process.env.TUNELIO_KEY } }
);
const data = await res.json();
console.log(data.full_text);
console.log(data.segments); // [{ start: 1.36, duration: 1.68, text: "..." }]import os, requests
res = requests.get(
"https://tunelio.dev/transcript",
params={"url": "dQw4w9WgXcQ", "lang": "en", "format": "json"},
headers={"Authorization": f"Bearer {os.environ['TUNELIO_KEY']}"}
)
data = res.json()
print("Title:", data["title"])
print("Full text:", data["full_text"])
for seg in data["segments"]:
print(f"[{seg['start']}s -> +{seg['duration']}s] {seg['text']}"){
"video_id": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"language": "en",
"language_name": "English",
"is_generated": false,
"type": "manual",
"available_languages": [
{ "code": "en", "name": "English", "is_generated": false, "type": "manual" },
{ "code": "es", "name": "Spanish", "is_generated": true, "type": "auto" }
],
"segments_count": 61,
"segments": [
{ "start": 18.64, "duration": 3.24, "text": "We're no strangers to love" },
{ "start": 21.88, "duration": 2.60, "text": "You know the rules and so do I" }
],
"full_text": "We're no strangers to love You know the rules and so do I …",
"status": "ok"
}JSON 响应包含视频 ID 和标题、实际提供的语言(language、language_name)、是否自动生成(is_generated、type)、available_languages 列表、segments_count、segments 数组和 full_text。完全没有字幕的视频返回 404 且不计费 —— 失败的请求会自动退还额度。
输出格式
- json(默认)
- 含 start、duration 和 text 的结构化片段,外加 full_text 与语言目录 —— 适合应用、RAG 流水线和分析。
- text
- 整段转录的纯文本(text/plain)—— 适合摘要、搜索索引和 LLM 提示词。
- srt
- SubRip 字幕(text/srt)—— 适合视频播放器、编辑器和压制工具。
- vtt
- WebVTT(text/vtt)—— 适合 HTML5 <track> 和网页播放器。
参数
- url
- YouTube watch、shorts、embed 或 youtu.be 链接,或 11 位视频 ID。必填。
- lang
- 语言代码,如 en、es、de、hi、zh。默认 en。type=any 时,Tunelio 会依次回退到英文和第一个可用轨道,并告诉你实际使用了哪一个。
- type
- any(优先人工字幕,回退到自动生成)、manual(仅人工字幕)或 auto(仅自动生成)。默认 any。
- format
- json、text、srt 或 vtt。默认 json。
开发者用它构建什么
价格
一次转录请求消耗 6 个额度,与 /info 相同。新账号获得 100 个免费额度 —— 足够十六次转录 —— 无需银行卡。付费套餐每月 9 美元起,含 100,000 个额度。
与自己运行 youtube-transcript-api 或 yt-dlp 相比
youtube-transcript-api 和 yt-dlp 这类开源库在笔记本上获取字幕很好用。到了服务器上,它们会继承 YouTube 的机器人验证:数据中心 IP 被挑战或封锁,年龄限制视频需要 cookies,YouTube 每次变动都意味着更新库并重新部署。当转录是产品功能而不是一次性脚本时,这些都是真实成本。
Tunelio 把这些工作移到服务端。你保留一次 HTTPS 调用和一个不随 YouTube 变化的 JSON 契约。如果你只是偶尔在自己机器上需要转录,免费库是正确的工具;如果转录在你的产品里,API 比维护更便宜。
常见问题
没有人工字幕的视频也能用吗?
可以。type=any(默认)时,没有人工轨道的视频会返回 YouTube 的自动生成字幕,并在响应中标记 is_generated: true,方便你区别处理。
支持哪些语言?
视频本身提供的所有语言 —— 人工轨道和自动生成轨道。用 lang 指定代码;响应会列出全部 available_languages,方便你提供选择器。
时间戳有多精确?
它们是 YouTube 自己的字幕时间:每个片段带有以秒计的开始时间和时长,精确到百分之一秒,与播放器显示的完全一致。
视频没有字幕会怎样?
API 返回 404 并附清晰说明,该请求的额度会自动退还。私密和不可用的视频同样返回 404。
有速率限制吗?
Trial 和 Pro 账号有每分钟请求上限,见价格页;Ultra 和 Mega 套餐不限请求速率。你为额度付费,而不是为请求次数付费。