用途
YouTube Playlist 用于处理与 YouTube 播放列表相关的任务：当用户粘贴播放列表链接或 ID、要求列出播放列表中的视频、浏览播放列表内容，或需要按顺序处理整个播放列表时，可使用该技能。它通过 TranscriptAPI.com 浏览播放列表并获取视频字幕。
主要能力
- 分页列出播放列表中的视频，每页 100 个。
- 返回视频信息，包括 videoId、标题、频道 ID、频道名称、频道 handle、时长文本、观看次数文本、缩略图以及索引。
- 返回播放列表信息，包括标题、视频数量、描述、所有者名称和观看次数。
- 支持通过 continuation_token 翻页，直到 has_more 为 false 或 continuation_token 为 null。
- 可结合字幕接口，从播放列表中的某个视频获取字幕（支持 text 格式、时间戳和元数据）。
- 若不知道播放列表 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）并阻止请求。
API 参考
完整 OpenAPI 规范见 transcriptapi.com/openapi.json，可查阅最新参数和 schema。
列出播放列表视频
GET /api/v2/youtube/playlist/videos — 每页 1 信用点。
参数：
- playlist（条件必填）：YouTube 播放列表 URL 或播放列表 ID（PL/UU/LL/FL/OL 前缀）。
- continuation（条件必填）：非空字符串。
playlist 与 continuation 必须且只能提供一个。
接受的播放列表 ID 前缀：
- PL — 用户创建的播放列表
- UU — 频道上传播放列表
- LL — 点赞视频
- FL — 收藏
- OL — 其他系统播放列表
第一页请求示例：
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_PLAYLIST_ID Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
后续页请求示例：
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
分页流程：
- 首次请求 ?playlist=PLxxx — 返回前 100 个视频和 continuation_token。
- 下一次请求 ?continuation=TOKEN — 返回接下来 100 个和新 token。
- 重复直到 has_more 为 false 或 continuation_token 为 null。
工作流：播放列表 → 字幕
- 列出播放列表视频：
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_PLAYLIST_ID Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
- 获取播放列表中某个视频的字幕：
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
不知道播放列表 ID 时
可先从频道查找播放列表（每页 1 信用点），再列出其中一个播放列表的视频：
- 列出频道的播放列表：
GET https://transcriptapi.com/api/v2/youtube/channel/playlists?channel=@TED Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
- 列出所选播放列表中的视频（playlistId 来自第 1 步）：
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PLAYLIST_ID Authorization: Bearer $TRANSCRIPT_API_KEY User-Agent: YourAgent/1.0
从 URL 提取播放列表 ID
从 https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf 中，播放列表 ID 是 PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf。也可以直接将完整 URL 传给 playlist 参数。
错误处理
- 400：两个参数都提供或都未提供 — 只提供 playlist 或 continuation 之一。
- 402：无信用点 — 前往 transcriptapi.com/billing。
- 403/1010：Cloudflare 拦截 — 添加或修正 User-Agent 请求头。
- 404：播放列表未找到 — 检查播放列表是否为公开。
- 408：超时 — 重试一次。
- 422：播放列表格式无效 — 必须是有效的播放列表 URL 或 ID。
计费与限制
每页 1 信用点。免费额度：100 信用点，每分钟 300 次请求。
复制粘贴示例
本文件中每个请求的可直接运行的一行命令见 references/curl-examples.md。