用途
Transcript 用于获取 YouTube 视频的字幕（转录文本）。当需要视频的口语内容时使用，即使未明确要求也可触发，例如：粘贴视频链接或 ID、请求总结、引用或翻译视频内容。
主要能力
- 通过 TranscriptAPI.com 获取视频转录文本。
- 接受多种输入形式：完整 URL（youtube.com/watch?v=ID）、短 URL（youtu.be/ID）、Shorts（youtube.com/shorts/ID）或纯 11 位视频 ID。
- 支持两种输出格式：json 与 text。
- 可选择是否包含时间戳（include_timestamp）。
- 可选择是否附带元数据（send_metadata），包括标题、作者名称、作者链接、缩略图。
- 返回语言信息与 video_id。
使用方式
配置
若未设置 $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。
默认建议：除非用户另有指定，始终使用 format=text&include_timestamp=true&send_metadata=true。
响应示例（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 } ], "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=text）
{ "video_id": "dQw4w9WgXcQ", "language": "en", "transcript": "[00:00:18] We're no strangers to love\n[00:00:21] You know the rules...", "metadata": {...} }
错误处理
- 401：API 密钥错误。检查密钥或重新配置。
- 402：无 credits。在 transcriptapi.com/billing 充值。
- 403/1010：Cloudflare 阻止。添加或修正 User-Agent 头。
- 404：无转录。视频可能未启用字幕。
- 408：超时。2 秒后重试一次。
- 429：被限流。等待后重试。
适用场景
- 需要视频口语内容进行总结、引用或翻译。
- 需要精确时间戳来引用特定时刻时，使用 format=json。
- 需要干净文本用于翻译或分析时，使用 include_timestamp=false。
- 长视频可先总结要点，再按需提供完整转录。
限制
- 依赖 TranscriptAPI.com 服务与 $TRANSCRIPT_API_KEY。
- 每次成功请求消耗 1 credit，错误不计费。
- 免费额度：100 credits，每分钟 300 次请求。
- 若视频未启用字幕，将返回 404。
- 必须携带有效的 User-Agent 头，否则会被 Cloudflare 阻止。
其他
每个请求的可直接运行示例见 references/curl-examples.md。