SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场youtube-data

youtube-data

数据与分析

查看项目

更新于 10-16 11:16

技能介绍

用途

youtube-data 是一个用于从 YouTube Data API v3 检索数据的技能。它的核心原则是“仅做数据检索”——只负责抓取并返回结构化数据，不生成文字内容或视觉素材。

适用时机包括：

  • 在 YouTube 上搜索符合查询或条件的视频
  • 获取某个视频或频道的详细统计数据
  • 抓取视频字幕/说明文字用于分析
  • 读取和分析视频评论
  • 查找与特定视频相关的视频
  • 按地区发现热门视频
  • 提取带时间过滤、搜索和分段功能的增强字幕

前提条件

  • YOUTUBE_API_KEY —— 在环境变量或 ~/.claude/.env 中设置，可从 Google Cloud Console 获取
  • 推荐使用 uv，或使用 Python 3.10+ 并安装依赖

使用 uv（推荐，零配置）：依赖通过 PEP 723 内联声明，首次运行时自动安装，只需使用 uv run。

使用 pip（备选）：

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

主要能力与使用方式

脚本 scripts/youtube_api.py 是一个自包含的 YouTube Data API 脚本，包含 8 个子命令。

快速开始示例：

  • 搜索视频：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "python tutorial" --max-results 5
  • 获取视频详情：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py video "dQw4w9WgXcQ"
  • 获取字幕：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en
  • 获取频道信息：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"
  • 获取评论：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies
  • 查找相关视频：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5
  • 获取热门视频：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py trending --region US --max-results 10
  • 增强多视频字幕：uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" --format merged --include-metadata --language en

子命令说明：

  • search：搜索 YouTube 视频，支持高级过滤
  • video：获取视频详细信息
  • channel：获取频道详细信息
  • comments：获取视频评论
  • transcript：获取视频字幕/说明文字
  • related：获取与特定视频相关的视频
  • trending：按地区获取热门视频
  • enhanced-transcript：带过滤功能的高级多视频字幕

search 参数：QUERY（搜索查询字符串）；--max-results N（结果数量，默认 10，最大 50）；--channel-id ID（按频道过滤）；--order ORDER（排序：date、rating、viewCount、relevance、title）；--duration DURATION（过滤：short <4 分钟、medium 4-20 分钟、long >20 分钟）；--published-after DATE（ISO 日期过滤）；--published-before DATE（ISO 日期过滤）；--region CODE（ISO 国家代码）。

video 返回：标题、描述、发布日期、频道、标签、观看/点赞/评论数、时长、缩略图。

channel 返回：标题、描述、订阅/视频/观看数、自定义 URL、缩略图。

comments 参数：--max-results N（评论数，默认 20）；--order ORDER（排序：relevance 默认或 time）；--include-replies（包含回复串）；--page-token TOKEN（分页令牌）。

transcript 参数：--language CODE（语言代码，如 en、ko、fr）。返回带时间戳的分段和带时间戳的全文。

related 参数：--max-results N（结果数量，默认 10）。

trending 参数：--region CODE（ISO 国家代码，默认 US）；--max-results N（结果数量，默认 5）。

enhanced-transcript 参数：VIDEO_IDS（一个或多个视频 ID，最多 5 个）；--language CODE（语言代码）；--format FORMAT（输出：raw、timestamped 默认、merged）；--start-time SECONDS（从该时间开始过滤）；--end-time SECONDS（过滤到该时间）；--search QUERY（在字幕文本中搜索）；--case-sensitive（区分大小写搜索）；--segment-method METHOD（分段：equal 默认、smart）；--segment-count N（分段数量，默认 1）；--include-metadata（随字幕包含视频详情）。

返回结构

所有子命令都会向 stdout 输出 JSON，结构一致：

{ "success": true, "data": { ... }, "error": null, "metadata": { "timestamp": "2025-01-26T12:00:00", ... } }

失败时 success 为 false，data 为 null，error 包含错误信息。退出码成功为 0，失败为 1。

Python API

可直接从其他技能的脚本中导入：

import sys from pathlib import Path sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts"))) from youtube_api import search_videos, get_video_details, get_video_transcript

可用函数包括：search_videos(query, ...)、get_video_details(video_id)、get_channel_details(channel_id)、get_video_comments(video_id, ...)、get_video_transcript(video_id, ...)、get_related_videos(video_id, ...)、get_trending_videos(region, ...)、get_enhanced_transcript(video_ids, ...)。所有函数返回相同的 {success, data, error, metadata} 字典。

下游技能集成

模式一：CLI 封装（推荐用于智能体）

result=$(uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "AI tutorials" --max-results 5) echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['items'][0]['title'])"

模式二：Python 导入并设置自定义默认值，示例脚本标注 requires-python >=3.10，依赖包括 google-api-python-client>=2.169.0、youtube-transcript-api>=1.0.3、python-dotenv>=1.1.0，可定义一个 search 并抓取主题热门视频字幕的函数。

环境变量

  • YOUTUBE_API_KEY：YouTube Data API v3 密钥，必需，默认无

适用场景与限制

该技能适用于需要对 YouTube 平台进行数据化分析、内容调研、字幕与评论提取，以及为下游技能提供结构化 YouTube 数据的场景。其限制包括：仅做数据检索，不生成文字内容或视觉素材；需要有效的 API 密钥；受 YouTube Data API 每日配额约束（默认 10,000 单位），配额超限会返回 HttpError 403 quotaExceeded，需等待配额重置或申请提升；增强字幕最多支持 5 个视频 ID；部分视频可能未启用字幕或需更换语言代码。脚本会对限流请求自动重试（3 次，指数退避）。

故障排查

  • “uv: command not found”：安装 uv，例如 curl -LsSf https://astral.sh/uv/install.sh | sh 或 brew install uv
  • “Required packages not installed”：使用 uv run 而非 python3 以自动安装依赖，或手动执行 pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt
  • “YOUTUBE_API_KEY environment variable not set”：在 shell、~/.claude/.env 或本地 .env 中设置 YOUTUBE_API_KEY
  • “HttpError 403: quotaExceeded”：等待配额重置或申请配额提升
  • “No transcript available”：视频可能未启用字幕，尝试不同的 --language 代码，其他语言可能有自动生成字幕

参考资料：references/youtube-data-api.md，包含 YouTube Data API v3 的端点、配额和响应结构。