video-transcript

视频转录文本

通过 TranscriptAPI.com 提取视频转录文本。

设置

如果未设置 $TRANSCRIPT_API_KEY，请阅读 references/auth-setup.md，并按照其中的说明获取并保存密钥。

必需的请求头

每个请求都需要两个请求头：

• Authorization： Bearer $TRANSCRIPT_API_KEY
• User-Agent： 已知时填写 Agent 的名称和版本（例如，HermesAgent/0.11.0、ClaudeCode/1.0）。版本可选，仅填写 Agent 名称也可以。不要省略此请求头，也不要发送未修改的默认值，否则 Cloudflare 将返回 403（错误代码 1010）并阻止请求。

GET /api/v2/youtube/transcript

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

参数	必需	默认值	取值
video_url	是	—	YouTube URL 或 11 位视频 ID
format	否	json	json（结构化），text（可读）
include_timestamp	否	true	true、false
send_metadata	否	false	true、false

接受的 URL 格式：

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://youtube.com/shorts/VIDEO_ID
• 纯视频 ID：dQw4w9WgXcQ

响应（format=text&send_metadata=true）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "[00:00:18] We're no strangers to love\n[00:00:21] You know the rules...",
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author_name": "Rick Astley",
    "author_url": "https://www.youtube.com/@RickAstley",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  }
}

响应（format=json）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 },
    { "text": "You know the rules and so do I", "start": 21.5, "duration": 2.8 }
  ]
}

提示

• 先将较长的转录文本总结为要点，并在用户提出请求时提供全文。
• 需要精确时间戳以引用特定片段时，请使用 format=json。
• 使用 send_metadata=true 获取视频标题和频道信息，作为上下文。
• 同样适用于 YouTube Shorts。

错误

代码	含义	操作
401	API 密钥无效	检查密钥或重新设置
402	额度不足	在 transcriptapi.com/billing 充值
403/1010	被 Cloudflare 拦截	添加或修正 User-Agent 请求头
404	没有转录文本	视频可能未启用字幕
408	超时	2 秒后重试一次

每次成功请求消耗 1 个额度。错误不会消耗额度。免费套餐：100 个额度，每分钟 300 个请求。

可直接复制粘贴的示例

此文件中的每个请求都有一个可直接运行的单行示例：references/curl-examples.md