Communitygithub.com

Yrzhe/claude-skills

YouTube Data API v3 完整封装 - 搜索视频、获取视频/频道/播放列表详情、获取评论、下载字幕等。支持按时间、观看次数、评级等过滤和排序。

claude-skills 是什么?

此技能基于 YouTube Data API v3 官方文档,提供了一个完整的命令行工具封装,使 AI 代理(如 Claude Code)能够直接与 YouTube 数据进行交互。用户可以通过简单的 Python 命令搜索视频、获取视频详情和统计信息、探索频道和播放列表、管理评论,甚至下载字幕。该工具支持丰富的过滤和排序选项(按时间、观看次数、评级等),并提供了多种数据输出格式(JSON、CSV、简易文本)。它全面涵盖了 YouTube 数据 API 的核心功能(搜索、视频、频道、播放列表、评论、字幕),并内置了错误处理和配额管理建议,适合进行大规模的数据分析、内容聚合和自动化操作。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yrzhe/claude-skills/tree/HEAD/plugins/youtube-data-api/skills/youtube-data-api

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 密钥

  1. 访问 Google Cloud Console
  2. 创建新项目或选择现有项目
  3. 启用 YouTube Data API v3
  4. 创建凭据 → API 密钥
  5. (可选)将 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请求过多降低请求频率

配额优化技巧

  1. 使用 fields 参数仅请求所需字段
  2. 批量请求使用逗号分隔的 ID 列表
  3. 缓存结果以避免重复请求
  4. 使用 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

附加资源

相关技能