youtube-data

YouTube 数据

从 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

快速开始

搜索视频：

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

脚本参考

scripts/youtube_api.py

独立的 YouTube Data API 脚本，包含 8 个子命令。

子命令

子命令	描述
search	使用高级筛选条件搜索 YouTube 视频
video	获取视频的详细信息
channel	获取频道的详细信息
comments	获取视频评论
transcript	获取视频字幕稿／字幕
related	获取与特定视频相关的视频
trending	按地区获取热门视频
enhanced-transcript	支持筛选的高级多视频字幕稿

search

youtube_api.py search QUERY [OPTIONS]

Arguments:
  QUERY                          Search query string

Options:
  --max-results N                Number of results (default: 10, max: 50)
  --channel-id ID                Filter by channel
  --order ORDER                  Sort: date, rating, viewCount, relevance, title
  --duration DURATION            Filter: short (<4min), medium (4-20min), long (>20min)
  --published-after DATE         ISO date filter (e.g. 2024-01-01T00:00:00Z)
  --published-before DATE        ISO date filter
  --region CODE                  ISO country code (e.g. US, GB, JP)

video

youtube_api.py video VIDEO_ID

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

channel

youtube_api.py channel CHANNEL_ID

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

comments

youtube_api.py comments VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of comments (default: 20)
  --order ORDER                  Sort: relevance (default) or time
  --include-replies              Include reply threads
  --page-token TOKEN             Pagination token

transcript

youtube_api.py transcript VIDEO_ID [OPTIONS]

Options:
  --language CODE                Language code (e.g. en, ko, fr)

返回：带时间戳的片段，以及含时间戳的完整文本。

related

youtube_api.py related VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of results (default: 10)

trending

youtube_api.py trending [OPTIONS]

Options:
  --region CODE                  ISO country code (default: US)
  --max-results N                Number of results (default: 5)

enhanced-transcript

youtube_api.py enhanced-transcript VIDEO_ID [VIDEO_ID...] [OPTIONS]

Arguments:
  VIDEO_IDS                      One or more video IDs (max 5)

Options:
  --language CODE                Language code
  --format FORMAT                Output: raw, timestamped (default), merged
  --start-time SECONDS           Filter from this time
  --end-time SECONDS             Filter until this time
  --search QUERY                 Search within transcript text
  --case-sensitive               Case-sensitive search
  --segment-method METHOD        Segmentation: equal (default), smart
  --segment-count N              Number of segments (default: 1)
  --include-metadata             Include video details with transcript

返回结构

所有子命令都会将 JSON 输出到 stdout，并采用以下统一结构：

{
  "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
result = search_videos("python tutorial", max_results=5)

# Get video details
result = get_video_details("dQw4w9WgXcQ")

# Get transcript
result = get_video_transcript("dQw4w9WgXcQ", language="en")

可用函数：

函数	描述
search_videos(query, ...)	搜索 YouTube 视频
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} 字典。

下游技能集成

模式 1：CLI 包装器（推荐用于 Agent）

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'])"

模式 2：使用自定义默认值导入 Python

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-api-python-client>=2.169.0",
#     "youtube-transcript-api>=1.0.3",
#     "python-dotenv>=1.1.0",
# ]
# ///

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

def research_topic(topic: str, count: int = 10) -> list:
    """Search and get transcripts for top videos on a topic."""
    search_result = search_videos(topic, max_results=count)
    if not search_result["success"]:
        return []
    videos = search_result["data"]["items"]
    for v in videos:
        t = get_video_transcript(v["videoId"], language="en")
        v["transcript"] = t["data"]["text"] if t["success"] else None
    return videos

环境变量

变量	描述	默认值
YOUTUBE_API_KEY	YouTube Data API v3 密钥	必填

故障排除

“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”

• YouTube Data API 有每日配额（默认 10,000 个单位）
• 等待配额重置，或申请提高配额
• 脚本会自动重试受速率限制的请求（采用指数退避，最多尝试 3 次）

“No transcript available”

• 视频可能未启用字幕
• 尝试使用其他 --language 代码
• 其他语言可能提供自动生成的字幕

参考资料

• references/youtube-data-api.md — YouTube Data API v3 端点、配额和响应结构