captions 是一个用于从 YouTube 视频中提取字幕（closed captions）的技能，底层通过 TranscriptAPI.com 服务实现。当需要视频的字幕、副标题或视频中口述的文字内容时，都可以使用该技能，即便用户没有明确说出提取字幕的请求（例如仅粘贴了视频链接或视频 ID、希望阅读视频内容等）也适用。
用途 该技能主要用于获取 YouTube 视频的字幕文本，可用于需要字幕内容、时间轴对齐或视频口述内容的场景。
主要能力
- 通过 TranscriptAPI.com 提取 YouTube 视频的隐藏字幕。
- 支持两种返回格式：format=json 返回结构化字幕数组，包含每条字幕的 text、start（距视频开始的秒数）和 duration（字幕显示时长），并可配合 send_metadata 返回视频元数据（标题、作者名、缩略图 URL）；format=text 返回可直接阅读的纯文本，可选择是否保留时间戳。
- 支持通过 video_url 参数传入 YouTube 链接或视频 ID。
使用方式
- 配置：如果未设置 $TRANSCRIPT_API_KEY 环境变量，需阅读 references/auth-setup.md 并按其说明获取并保存密钥。
- 请求头：每个请求都需要两个请求头——Authorization: Bearer $TRANSCRIPT_API_KEY 以及 User-Agent（注明你的 agent 名称与版本，版本可选，例如 HermesAgent/0.11.0、ClaudeCode/1.0）。不要省略该请求头或发送裸默认值，否则 Cloudflare 会返回 403（错误码 1010）并拦截请求。
- 接口：GET https://transcriptapi.com/api/v2/youtube/transcript
- 参数：video_url（必填，YouTube URL 或视频 ID）；format（可选，默认 json，可选 json 或 text）；include_timestamp（可选，默认 true，可选 true 或 false）；send_metadata（可选，默认 false，可选 true 或 false）。
- 响应示例（format=json）：返回 video_id、language、transcript 数组（每项含 text、start、duration）以及 metadata。
- 响应示例（format=text）：返回 video_id、language、transcript 字符串（带时间戳如 [00:00:18]）。
使用建议
- 需要时间同步的字幕（如无障碍工具、时间轴分析）时使用 format=json。
- 需要干净的阅读文本时使用 format=text 并设置 include_timestamp=false。
- 大多数视频都提供自动生成的字幕；手动上传的 CC 质量更高。
适用场景 适用于需要 YouTube 视频字幕文本、时间轴信息或视频口述内容的场景，例如无障碍处理、时间轴分析、纯文本阅读等。
限制与错误处理
- 每次请求消耗 1 个额度；免费层为 100 额度，每分钟 300 次请求。
- 错误码说明：401 表示 API 密钥错误（检查密钥）；402 表示无额度（前往 transcriptapi.com/billing）；403/1010 表示 Cloudflare 拦截（添加或修正 User-Agent 请求头）；404 表示无字幕（视频未启用 CC）；408 表示超时（等待 2 秒后重试一次）。
- 更多可直接运行的请求示例见 references/curl-examples.md。