video-transcript

用途

video-transcript 用于在需要把视频内容提取为文本时使用。适用于以下请求：用户粘贴 YouTube 链接或视频 ID，或提出转写、总结、引用、翻译、视频转文字等需求。它以技能形式提供，通过 TranscriptAPI.com 提取视频字幕。

主要能力

通过 TranscriptAPI.com 从视频中提取字幕（transcript）。
支持传入 YouTube URL 或 11 位视频 ID。
支持两种输出格式：json（结构化）与 text（可读）。
可选是否在结果中包含时间戳（include_timestamp，默认 true）。
可选是否返回视频元数据（send_metadata，默认 false），包括标题、作者名称、作者主页与缩略图。
可识别视频语言（响应中包含 language 字段）。
同样支持 YouTube Shorts。

使用方式

配置

若环境变量 $TRANSCRIPT_API_KEY 未设置，请阅读 references/auth-setup.md 并按其说明获取并保存该密钥。

必需请求头

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

Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: 你的智能体名称与版本（如已知），例如 HermesAgent/0.11.0、ClaudeCode/1.0。版本可选，仅提供智能体名称也可以。不要省略该请求头或发送默认值，否则 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

适用场景

将 YouTube 视频或短视频内容转写为文本。
对视频内容进行总结、引用或翻译。
需要带精确时间戳的台词引用时。
需要视频标题、频道等元数据作为上下文时。

限制

依赖 TranscriptAPI.com 服务及有效 API 密钥。
请求受额度限制，每次成功请求消耗 1 个额度；免费额度为 100 额度、每分钟 300 次请求。
若视频未启用字幕，将返回 404，无法获取字幕。
请求必须携带 User-Agent，否则可能被 Cloudflare 以 403/1010 阻断。
关于付费与价格的更多信息暂未提供。