YouTube Data API v3 技能
基于官方 YouTube Data API v3 文档的完整封装。
配置
API 密钥设置
# 选项1:环境变量(推荐)
export YOUTUBE_API_KEY="YOUR_API_KEY_HERE"
# 选项2:直接编辑配置文件
# 编辑 ~/.claude/skills/youtube-data-api/scripts/config.py
获取 API 密钥
- 访问 Google Cloud Console
- 创建新项目或选择现有项目
- 启用 YouTube Data API v3
- 创建凭据 → API 密钥
- (可选)将 API 密钥限制为仅限 YouTube Data API
配额限制
| 操作类型 | 配额消耗(单位) |
|---|---|
| 读取操作(列表) | 1 |
| 搜索请求 | 100 |
| 写入操作(插入/更新/删除) | 50 |
| 视频上传 | 1600 |
默认每日配额:10,000 单位
核心功能
1. 搜索视频(搜索)
配额消耗:100 单位/请求
# 基本搜索
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python tutorial" \
--max-results 25
# 按时间过滤(上周)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "machine learning" \
--published-after "7d" \
--type video
# 按观看次数排序
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "React hooks" \
--order viewCount \
--type video
# 仅限高清视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "4K nature" \
--video-definition high \
--type video
# 包含字幕的视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "TED talk" \
--video-caption closedCaption \
--type video
# 直播视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "gaming" \
--event-type live \
--type video
# 按区域过滤
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "news" \
--region-code US \
--relevance-language en
# 按视频时长过滤
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "documentary" \
--video-duration long \
--type video
搜索参数参考
| 参数 | 描述 | 值 |
|---|---|---|
--query, -q | 搜索关键词 | 支持布尔运算符(python AND tutorial) |
--type | 资源类型 | video, channel, playlist |
--max-results | 结果数量 | 1-50,默认为 25 |
--order | 排序方式 | relevance(默认)、date、rating、viewCount、title |
--published-after | 发布于...之后 | 1d、7d、30d、1y 或 ISO 8601 格式 |
--published-before | 发布于...之前 | 同上 |
--region-code | 地区代码 | ISO 3166-1(例如 US、CN、JP) |
--relevance-language | 语言 | ISO 639-1(例如 en、zh、ja) |
--video-duration | 视频时长 | short(<4分钟)、medium(4-20分钟)、long(>20分钟) |
--video-definition | 视频清晰度 | high(高清)、standard(标清) |
--video-caption | 字幕 | closedCaption(有字幕)、none(无字幕) |
--video-dimension | 视频维度 | 2d、3d |
--event-type | 直播状态 | live(直播中)、completed(已结束)、upcoming(即将开始) |
--channel-id | 限制到频道 | 频道 ID |
--safe-search | 安全搜索 | none、moderate、strict |
2. 获取视频详情(视频)
配额消耗:1 单位/请求
# 获取单个视频详情
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--id "dQw4w9WgXcQ" \
--parts snippet,statistics,contentDetails
# 批量获取多个视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--id "dQw4w9WgXcQ,jNQXAC9IVRw,9bZkp7q19f0" \
--parts snippet,statistics
# 获取热门视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--chart mostPopular \
--region-code US \
--max-results 50
# 按类别获取热门视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--chart mostPopular \
--video-category-id 10 \
--region-code JP
视频部分参考
| 部分 | 内容 |
|---|---|
snippet | 标题、描述、缩略图、频道信息、发布时间、标签 |
statistics | 观看次数、点赞数、评论数 |
contentDetails | 时长、清晰度、字幕信息、区域限制 |
status | 上传状态、隐私设置、许可证 |
player | 嵌入式播放器 HTML |
topicDetails | 相关主题 ID |
recordingDetails | 录制地点、日期 |
liveStreamingDetails | 直播信息(开始/结束时间、观看人数) |
视频类别 ID 参考
| ID | 类别 | ID | 类别 |
|---|---|---|---|
| 1 | 电影与动画 | 20 | 游戏 |
| 2 | 汽车与交通 | 22 | 人物与博客 |
| 10 | 音乐 | 23 | 喜剧 |
| 15 | 宠物与动物 | 24 | 娱乐 |
| 17 | 体育 | 25 | 新闻与政治 |
| 19 | 旅行与活动 | 26 | 教程与风格 |
| 27 | 教育 | 28 | 科学与技术 |
3. 获取频道信息(频道)
配额消耗:1 单位/请求
# 按频道 ID 获取
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
--id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
--parts snippet,statistics,contentDetails
# 按用户名获取
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
--for-username "GoogleDevelopers" \
--parts snippet,statistics
# 按句柄(@用户名)获取
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
--for-handle "@Google" \
--parts snippet,statistics,brandingSettings
频道部分参考
| 部分 | 内容 |
|---|---|
snippet | 频道名称、描述、缩略图、国家 |
statistics | 订阅者数、视频数、总观看次数 |
contentDetails | 相关播放列表(上传、喜欢等) |
brandingSettings | 频道横幅、关键词、默认语言 |
topicDetails | 频道主题 |
status | 频道状态(长视频上传权限等) |
4. 获取播放列表(播放列表)
配额消耗:1 单位/请求
# 按 ID 获取播放列表
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
--id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
--parts snippet,contentDetails
# 获取一个频道的所有播放列表
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
--channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
--max-results 50
5. 获取播放列表视频(播放列表项目)
配额消耗:1 单位/请求
# 获取播放列表中的所有视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
--playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
--max-results 50
# 分页获取
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
--playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
--page-token "NEXT_PAGE_TOKEN"
6. 获取评论(评论与评论线程)
配额消耗:1 单位/请求
# 获取视频的所有评论(顶级)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
--video-id "dQw4w9WgXcQ" \
--max-results 100 \
--order relevance
# 获取频道的评论
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
--channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
--max-results 50
# 获取评论的回复
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comment-replies \
--parent-id "COMMENT_ID" \
--max-results 50
评论排序选项
| 排序方式 | 描述 |
|---|---|
relevance | 按相关性(默认) |
time | 按时间(最新优先) |
7. 获取字幕(字幕)
配额消耗:列表 1 单位/请求,下载 50 单位/请求
# 列出视频的所有字幕轨道
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
--video-id "dQw4w9WgXcQ" \
--list
# 下载字幕(需要 OAuth)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
--video-id "dQw4w9WgXcQ" \
--download \
--caption-id "CAPTION_ID" \
--format srt
注意:下载字幕需要视频所有者授权(OAuth)。对于公开视频,可以使用 yt-dlp 获取自动生成的字幕。
使用 yt-dlp 获取字幕(替代方法)
# 安装 yt-dlp
pip install yt-dlp
# 列出可用的字幕
yt-dlp --list-subs "https://www.youtube.com/watch?v=VIDEO_ID"
# 下载字幕(跳过视频)
yt-dlp --write-sub --write-auto-sub --sub-lang en,zh-Hans --skip-download \
"https://www.youtube.com/watch?v=VIDEO_ID"
# 下载并转换为 SRT 格式
yt-dlp --write-sub --write-auto-sub --sub-lang en --sub-format srt --skip-download \
"https://www.youtube.com/watch?v=VIDEO_ID"
8. 获取视频类别(视频类别)
配额消耗:1 单位/请求
# 获取某个地区的视频类别
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
--region-code US
# 获取中国的视频类别
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
--region-code CN
9. 获取支持的地区和语言
配额消耗:1 单位/请求
# 获取支持的地区列表
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py regions
# 获取支持的语言列表
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py languages
常见用例示例
场景1:获取上周的热门主题视频
# 搜索过去 7 天内关于 "AI" 的视频,按观看次数排序
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "AI artificial intelligence" \
--published-after "7d" \
--order viewCount \
--type video \
--max-results 50 \
--output ai_trending.json
# 获取这些视频的详细统计信息
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--ids-from ai_trending.json \
--parts snippet,statistics,contentDetails \
--output ai_trending_details.json
场景2:分析频道的所有视频
# 1. 获取频道信息
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
--for-handle "@GoogleDevelopers" \
--parts snippet,statistics,contentDetails \
--output channel_info.json
# 2. 获取上传播放列表 ID(来自 contentDetails.relatedPlaylists.uploads)
# 3. 获取所有上传的视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
--playlist-id "UPLOADS_PLAYLIST_ID" \
--max-results 50 \
--all-pages \
--output channel_videos.json
场景3:获取带字幕的视频
# 1. 搜索视频
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "TED talk motivation" \
--video-caption closedCaption \
--type video \
--max-results 10 \
--output ted_videos.json
# 2. 使用 yt-dlp 下载字幕
for video_id in $(jq -r '.items[].id.videoId' ted_videos.json); do
yt-dlp --write-sub --write-auto-sub --sub-lang en --skip-download \
"https://www.youtube.com/watch?v=$video_id" \
-o "subtitles/%(id)s.%(ext)s"
done
场景4:分析视频评论
# 获取视频的所有评论
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
--video-id "VIDEO_ID" \
--max-results 100 \
--all-pages \
--output comments.json
# 评论数据包括:
# - 作者名称
# - 评论内容
# - 点赞数
# - 发布时间
# - 回复数量
输出格式
所有命令默认输出为 JSON,使用 --output 参数保存到文件。
# 输出到文件
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python" \
--output results.json
# CSV 格式(表格数据)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python" \
--format csv \
--output results.csv
# 简单输出(仅标题和 ID)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python" \
--format simple
分页
对于大数据集,API 使用 pageToken 进行分页:
# 自动获取所有页面
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python" \
--all-pages \
--max-total 500 \
--output all_results.json
# 手动分页
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python" \
--page-token "NEXT_PAGE_TOKEN"
错误处理
常见错误代码
| 代码 | 描述 | 解决方案 |
|---|---|---|
| 400 | 错误请求 | 检查参数格式 |
| 401 | 未授权 | 检查 API 密钥 |
| 403 | 配额超限或权限不足 | 检查配额或申请增加 |
| 404 | 资源未找到 | 验证 ID 是否正确 |
| 429 | 请求过多 | 降低请求频率 |
配额优化技巧
- 使用
fields参数仅请求所需字段 - 批量请求使用逗号分隔的 ID 列表
- 缓存结果以避免重复请求
- 使用 ETag检查资源是否已更新
# 仅获取所需字段(减小响应大小)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--id "VIDEO_ID" \
--fields "items(id,snippet(title,channelTitle),statistics(viewCount))"
需要 OAuth 的操作
以下操作需要用户授权(仅 API 密钥不足):
- 上传视频
- 更新视频元数据
- 删除视频
- 管理播放列表
- 发布/删除评论
安装与依赖
# 克隆仓库
git clone https://github.com/Yrzhe/claude-skills.git ~/.claude/skills/youtube-data-api
# 安装依赖
pip install -r ~/.claude/skills/youtube-data-api/requirements.txt
# requirements.txt 内容:
# requests>=2.25.0
# google-api-python-client>=2.0.0
# google-auth-oauthlib>=0.4.0
故障排除
API 密钥问题
# 检查 API 密钥是否已设置
echo $YOUTUBE_API_KEY
# 如果为空,请设置:
export YOUTUBE_API_KEY="your_key_here"
配额问题
- 搜索请求成本高(100 单位/请求)
- 考虑使用
--max-results(默认 25) - 按请求选择所需
--parts - 批量获取视频 ID 以获取详情
网络问题
# 测试连接
curl -I https://www.googleapis.com/youtube/v3
# 预期: 200 OK