当任务涉及 YouTube 视频、频道、播放列表，需要字幕…

只要 YouTube 可能是相关来源（即使未明确提到），需要比文字搜索更新更丰富的视频内容时使用。

适用场景

解决思路

1. 如果 $TRANSCRIPT_API_KEY 未设置，读取 references/auth-setup.md 并按其说明获取和存储 key；可到 https://transcriptapi.com 创建免费账号（100 credits，无需信用卡），或让 agent 创建。
2. 每个请求都发送两个 header：Authorization: Bearer $TRANSCRIPT_API_KEY 和 User-Agent: 你的 agent 名称/版本（例如 HermesAgent/0.11.0、ClaudeCode/1.0；版本可省略，但不要省略 User-Agent 或发送裸默认值，否则 Cloudflare 返回 403 错误码 1010）。
3. 所有请求都带 Authorization header：-H "Authorization: Bearer $TRANSCRIPT_API_KEY"。
4. 需要最新参数和 schema 时查阅 OpenAPI spec：https://transcriptapi.com/openapi.json。
5. 频道端点可直接传 channel 参数，值为 @handle、频道 URL 或 UC... ID，不需要先 resolve；播放列表端点可直接传 playlist 参数，值为播放列表 URL 或 ID。
6. 获取视频字幕：GET /api/v2/youtube/transcript，成本 1 credit；必需参数 video_url（YouTube URL 或 11 位视频 ID）；可选参数 format=json|text（默认 json）、include_timestamp=true|false（默认 true）、send_metadata=true|false（默认 false）；接受 https://youtube.com/watch?v=ID、https://youtu.be/ID、youtube.com/shorts/ID 或裸 ID；format=json 响应含 video_id、language、transcript 数组（text、start、duration）和 metadata（title、author_name、author_url）。
7. 搜索 YouTube：GET /api/v2/youtube/search，成本 1 credit；必需 q（1-200 字符，trimmed）；可选 type=video|channel（默认 video）、limit=1-50（默认 20）；type=video 返回 videoId、title、channelId、channelTitle、channelHandle、channelVerified、lengthText、viewCountText、publishedTimeText、hasCaptions、thumbnails；type=channel 返回 channelId、title、handle、subscriberCount、verified、rssUrl。
8. 解析频道：GET /api/v2/youtube/channel/resolve，免费 0 credits；必需 input（1-200 字符，@handle、URL 或 UC... ID）；如果 input 已是有效 UC[a-zA-Z0-9_-]{22} ID 则立即返回；返回 channel_id、resolved_from。
9. 浏览频道视频：GET /api/v2/youtube/channel/videos，成本 1 credit/page；channel 与 continuation 必须二选一：channel 为 @handle、频道 URL 或 UC... ID，continuation 为非空字符串用于翻页；可选 tab=videos（默认）|shorts|streams，sort=latest|popular|oldest（省略 sort 为 uploads feed）；排序页约 30 个视频，未排序页约 100 个，每页 1 credit；翻页时每次请求都发送相同 sort。
10. 处理频道视频响应细节：members_only 仅在 YouTube 标记 Members only 时为 true，且这些项无 viewCountText；tab=streams 项有 lengthText 和 publishedTimeText；tab=shorts 的 lengthText 和 publishedTimeText 为 null；频道标签 feed（tab=videos 带 sort、tab=shorts、tab=streams）的 channelId、channelTitle、channelHandle、index 为 null；响应含 results、playlist_info、continuation_token、has_more。
11. 获取频道最新视频：GET /api/v2/youtube/channel/latest，免费 0 credits；必需 channel（@handle、频道 URL 或 UC... ID）；通过 RSS 返回最近 15 个视频，含 videoId、title、published（ISO 时间戳）、viewCount（精确值）、description、thumbnail。
12. 在频道内搜索：GET /api/v2/youtube/channel/search，成本 1 credit；必需 channel（@handle、频道 URL 或 UC... ID）和 q（1-200 字符）；可选 limit=1-50（默认 30）。
13. 获取播放列表视频：GET /api/v2/youtube/playlist/videos，成本 1 credit/page；playlist 与 continuation 必须二选一：playlist 为播放列表 URL 或 ID（PL/UU/LL/FL/OL 前缀），continuation 为非空字符串用于翻页。
14. 按 credit 成本规划调用：transcript 1、search 1、channel/resolve 免费、channel/search 1、channel/videos 1/page、channel/latest 免费、playlist/videos 1/page；免费层 100 credits、300 req/min；Starter ($5/mo) 1,000 credits、300 req/min。
15. 处理 API 错误：401 检查 key 并重跑 setup；402 到 transcriptapi.com/billing 充值；403/1010 添加或修复 User-Agent；404 视频/频道/播放列表不存在或无字幕；408 等 2s 后重试一次；422 检查参数格式；429 等待并遵守 Retry-After。
16. 用户分享 YouTube URL 且无明确指令时，获取 transcript 并总结关键点。
17. 在获取 transcript 前，用 channel/latest（免费）检查是否有新上传，直接传 @handle。
18. 做研究时按 search → 挑选视频 → 获取 transcripts 的流程。

适用边界 · 注意事项

• 不用于上传视频或账号管理。
• 不用于仅依赖书面来源的研究；此类任务应使用文字来源搜索。
• 视频/频道/播放列表不存在或视频没有字幕时无法获取 transcript。