youtube-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

YouTube Data

YouTube 数据

Retrieve data from the YouTube Data API v3. Supports searching videos, fetching video/channel details, reading transcripts and comments, and discovering trending or related content.

Core principle: Data retrieval only — this skill fetches and returns structured data. It does not produce written content or visual assets.

通过YouTube Data API v3获取数据。支持搜索视频、获取视频/频道详情、提取字幕和查看评论，以及发现热门或相关内容。

**核心原则：**仅用于数据获取——该Skill仅获取并返回结构化数据，不生成书面内容或视觉资源。

When to Use

适用场景

Search YouTube for videos matching a query or criteria
Get detailed statistics for a specific video or channel
Fetch video transcripts/captions for analysis
Read and analyze video comments
Find videos related to a specific video
Discover trending videos by region
Extract enhanced transcripts with time filtering, search, and segmentation

在YouTube上搜索符合查询条件或特定标准的视频
获取特定视频或频道的详细统计数据
提取视频字幕用于分析
查看并分析视频评论
查找与特定视频相关的内容
按地区发现热门视频
提取支持时间过滤、搜索和分段的增强版字幕

Prerequisites

前置条件

```
YOUTUBE_API_KEY
```
— Set in environment or
```
~/.claude/.env
```
. Get from Google Cloud Console
```
uv
```
(recommended) or Python 3.10+ with dependencies installed

With
uv
(recommended — zero setup): Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use

uv run

With pip (fallback):

bash

pip install -r <skill_dir>/requirements.txt

```
YOUTUBE_API_KEY
```
— 需设置在环境变量或
```
~/.claude/.env
```
文件中。可从Google Cloud Console获取
```
uv
```
（推荐）或Python 3.10+环境，并安装依赖

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

uv run

命令即可。

使用pip（备选）：

bash

pip install -r <skill_dir>/requirements.txt

Quick Start

快速开始

Search for videos:

搜索视频：

bash

uv run <skill_dir>/scripts/youtube_api.py search "python tutorial" --max-results 5

bash

uv run <skill_dir>/scripts/youtube_api.py search "python tutorial" --max-results 5

Get video details:

获取视频详情：

bash

uv run <skill_dir>/scripts/youtube_api.py video "dQw4w9WgXcQ"

bash

uv run <skill_dir>/scripts/youtube_api.py video "dQw4w9WgXcQ"

Get transcript:

获取字幕：

bash

uv run <skill_dir>/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

bash

uv run <skill_dir>/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

Get channel info:

获取频道信息：

bash

uv run <skill_dir>/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

bash

uv run <skill_dir>/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

Get comments:

获取评论：

bash

uv run <skill_dir>/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

bash

uv run <skill_dir>/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

Find related videos:

查找相关视频：

bash

uv run <skill_dir>/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

bash

uv run <skill_dir>/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

Get trending videos:

获取热门视频：

bash

uv run <skill_dir>/scripts/youtube_api.py trending --region US --max-results 10

bash

uv run <skill_dir>/scripts/youtube_api.py trending --region US --max-results 10

Enhanced multi-video transcript:

增强版多视频字幕：

bash

uv run <skill_dir>/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

bash

uv run <skill_dir>/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

Script Reference

脚本参考

scripts/youtube_api.py

scripts/youtube_api.py

Self-contained YouTube Data API script with 8 subcommands.

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

Subcommands

子命令

Subcommand	Description
`search`	Search for YouTube videos with advanced filtering
`video`	Get detailed information about a video
`channel`	Get detailed information about a channel
`comments`	Get comments for a video
`transcript`	Get transcript/captions for a video
`related`	Get videos related to a specific video
`trending`	Get trending videos by region
`enhanced-transcript`	Advanced multi-video transcript with filtering

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

search

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)

youtube_api.py search QUERY [OPTIONS]

参数:
  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日期过滤（例如：2024-01-01T00:00:00Z）
  --published-before DATE        ISO日期过滤
  --region CODE                  ISO国家代码（例如：US、GB、JP）

video

video

youtube_api.py video VIDEO_ID

Returns: title, description, publish date, channel, tags, view/like/comment counts, duration, thumbnails.

youtube_api.py video VIDEO_ID

返回内容：标题、描述、发布日期、所属频道、标签、播放/点赞/评论数、时长、缩略图。

channel

channel

youtube_api.py channel CHANNEL_ID

Returns: title, description, subscriber/video/view counts, custom URL, thumbnails.

youtube_api.py channel CHANNEL_ID

返回内容：标题、描述、订阅数/视频数/播放数、自定义URL、缩略图。

comments

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

youtube_api.py comments VIDEO_ID [OPTIONS]

选项:
  --max-results N                评论数量（默认：20）
  --order ORDER                  排序方式：relevance（默认）或time
  --include-replies              包含回复线程
  --page-token TOKEN             分页令牌

transcript

transcript

youtube_api.py transcript VIDEO_ID [OPTIONS]

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

Returns: timestamped segments and full text with timestamps.

youtube_api.py transcript VIDEO_ID [OPTIONS]

选项:
  --language CODE                语言代码（例如：en、ko、fr）

返回内容：带时间戳的分段内容和完整带时间戳的文本。

related

related

youtube_api.py related VIDEO_ID [OPTIONS]

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

youtube_api.py related VIDEO_ID [OPTIONS]

选项:
  --max-results N                结果数量（默认：10）

trending

trending

youtube_api.py trending [OPTIONS]

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

youtube_api.py trending [OPTIONS]

选项:
  --region CODE                  ISO国家代码（默认：US）
  --max-results N                结果数量（默认：5）

enhanced-transcript

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

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

参数:
  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             包含视频详情与字幕

Return Structure

返回结构

All subcommands output JSON to stdout with this consistent structure:

json

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

On failure,

success

false

data

null

, and

error

contains the message. Exit code is

on success,

on failure.

所有子命令均向标准输出输出JSON，结构如下：

json

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

失败时，

success

为

false

，

data

为

null

，

error

包含错误信息。成功时退出码为

，失败时为

。

Python API

Direct import (from another skill's script):

直接导入（从其他Skill脚本中）：

python

import sys
from pathlib import Path
sys.path.insert(0, str(Path("<skill_dir>/scripts")))
from youtube_api import search_videos, get_video_details, get_video_transcript

python

import sys
from pathlib import Path
sys.path.insert(0, str(Path("<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")

undefined

result = get_video_transcript("dQw4w9WgXcQ", language="en")

undefined

Available functions:

可用函数：

Function	Description
`search_videos(query, ...)`	Search YouTube videos
`get_video_details(video_id)`	Get video details
`get_channel_details(channel_id)`	Get channel details
`get_video_comments(video_id, ...)`	Get video comments
`get_video_transcript(video_id, ...)`	Get video transcript
`get_related_videos(video_id, ...)`	Get related videos
`get_trending_videos(region, ...)`	Get trending videos
`get_enhanced_transcript(video_ids, ...)`	Enhanced multi-video transcript

All functions return the same

{success, data, error, metadata}

dict.

函数	描述
`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}

字典。

Downstream Skill Integration

下游Skill集成

Pattern 1: CLI wrapper (recommended for agents)

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

bash

result=$(uv run <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'])"

bash

result=$(uv run <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'])"

Pattern 2: Python import with custom defaults

模式2：带自定义默认值的Python导入

python

undefined

python

undefined

/// 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("<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

undefined

import sys from pathlib import Path sys.path.insert(0, str(Path("<skill_dir>/scripts"))) from youtube_api import search_videos, get_video_transcript

def research_topic(topic: str, count: int = 10) -> list: """搜索并获取主题相关热门视频的字幕。""" 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

undefined

Environment Variables

环境变量

Variable	Description	Default
`YOUTUBE_API_KEY`	YouTube Data API v3 key	Required

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

Troubleshooting

故障排除

"uv: command not found"

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

brew install uv

"Required packages not installed"

Use
```
uv run
```
instead of
```
python3
```
to auto-install dependencies

Or install manually:

pip install -r <skill_dir>/requirements.txt

"YOUTUBE_API_KEY environment variable not set"

Set
```
YOUTUBE_API_KEY
```
in your shell,
```
~/.claude/.env
```
, or local
```
.env
```

"HttpError 403: quotaExceeded"

YouTube Data API has a daily quota (default 10,000 units)
Wait until quota resets or request a quota increase
The script retries rate-limited requests automatically (3 attempts with exponential backoff)

"No transcript available"

Video may not have captions enabled
Try a different
```
--language
```
code
Auto-generated captions may be available in other languages

"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 <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

参考资料

references/youtube-data-api.md — YouTube Data API v3 endpoints, quotas, and response structures

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