跳到正文

YouTube 转录 API

发送一个 YouTube 链接,在同一请求中拿回转录文本:带时间戳的 JSON 片段,或可直接使用的 SRT、VTT 和纯文本。有人工字幕时返回人工字幕,没有时返回自动生成字幕 —— 并附完整语言列表,让你始终清楚拿到的是什么。

转录 API 做什么

YouTube 转录 API 把视频链接变成结构化的字幕数据。Tunelio 的 GET /transcript 端点解析视频,为你请求的语言挑选最佳字幕轨道(优先人工字幕而非自动生成),并返回每个片段及其开始时间和时长 —— 外加拼接好的全文和该视频提供的所有其他语言的目录。无需浏览器自动化、无需 cookies、无需维护 yt-dlp;只需带 API key 的一次 HTTPS 请求。

工作方式

1. 带链接调用 /transcript
任意 watch、shorts、embed 或 youtu.be 链接 —— 或仅视频 ID。可加 lang(默认 en)、type(any、manual 或 auto)和 format(json、text、srt 或 vtt)。
2. 我们在服务端解析字幕
Tunelio 用自己的提取集群从 YouTube 获取字幕轨道,因此机器人验证、IP 信誉和格式变化永远不会触及你的代码。
3. 直接使用响应
JSON 直接进入你的应用或 LLM 流水线;SRT 和 VTT 放进视频播放器;纯文本用于搜索索引和摘要。典型延迟约一秒。

可直接复制的示例

把 tnl_… 替换为控制台中的 API key。同一 key 也适用于 /info 和 /create。

cURL
curl -X GET "https://tunelio.dev/transcript?url=dQw4w9WgXcQ&lang=en&format=json" \
  -H "Authorization: Bearer tnl_…"
Node.js
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: "..." }]
Python
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。

开发者用它构建什么

LLM 与 RAG 流水线
把带时间戳的片段喂给模型,为每个分块保留开始时间,并把答案链接回视频中的精确秒数。
字幕与无障碍
为自己的播放器提供 SRT 或 VTT,翻译字幕,或在嵌入视频旁提供转录文本。
搜索与摘要
索引全文以便用户在视频内搜索;生成摘要、章节和精华片段。
机器人与自动化
回答 “12:30 时说了什么?” 的 Telegram 或 Discord 机器人、Zapier 式流程、内容审核。

价格

一次转录请求消耗 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 套餐不限请求速率。你为额度付费,而不是为请求次数付费。

阅读 API 文档