用途:让智能体获取 YouTube 视频字幕、搜索结果、频道与播放列表数据,从而对视频实际口播内容进行总结、引用、搜索或分析,无需用户手动复制粘贴。
主要能力:GET /transcript 获取字幕;GET /search 全局搜索视频或频道;GET /resolve 将频道 handle 解析为频道 ID(免费);GET /channel/latest 获取频道信息与最新视频(免费);GET /channel/videos 获取完整上传历史(分页);GET /channel/search 在频道内搜索(分页);GET /playlist 获取播放列表视频(分页)。
使用方式:每次调用需 API 密钥,来自环境变量 YOUTUBE_TRANSCRIPT_API_KEY 或用户已提供的密钥。若均无,技能可在用户明确同意并提供邮箱后,通过两步邮箱加验证码流程注册免费账户(100 积分,无需信用卡)。基础 URL 为 https://getyoutubetranscript.com/api/v1,密钥以 Authorization: Bearer <API_KEY> 或 x-api-key: <API_KEY> 发送。示例:curl -s "https://getyoutubetranscript.com/api/v1/transcript?v=jNQXAC9IVRw&language=en" -H "Authorization: Bearer $YOUTUBE_TRANSCRIPT_API_KEY"。
错误与分页:错误为 JSON,含稳定错误码(如 TRANSCRIPT_NOT_FOUND、PAYMENT_REQUIRED、RATE_LIMITED)与对应 HTTP 状态,应转达 message 字段而非猜测修复。分页端点返回不透明的 data.continuation_token,需原样作为 continuation 传回获取下一页,null 表示无更多页。
适用场景:用户需要获取、总结、引用或分析某视频字幕;搜索 YouTube 或某频道内内容;解析频道 handle、查看频道信息与上传历史;获取播放列表视频。
限制:字幕端点返回整段口播文本,不提供逐行时间戳;不替代环境特定验证、测试或专家审查;缺少必要输入、权限或安全边界时应停止并请求澄清。安全方面仅向 getyoutubetranscript.com 发起出站 HTTPS 请求,首次设置时使用用户明确提供的邮箱,不运行其他 shell 命令、不安装任何内容;未经用户明确确认,不得将新签发的 API 密钥写入 shell 配置文件或其他文件。最佳实践:优先复用已有密钥;注册前取得明确同意;不要重试 402 PAYMENT_REQUIRED;不要对 429 RATE_LIMITED 循环重试,应退避。相关技能:@youtube-full 为基于不同上游 API 的替代方案。