youtube-data

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

クイックスタート

動画を検索する：

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

8 つのサブコマンドを備えた、単体で動作する YouTube Data API スクリプトです。

サブコマンド

サブコマンド	説明
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 を標準出力に返します。

{
  "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 ラッパー（エージェント向け推奨）

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」

• 依存関係を自動でインストールするには、python3 の代わりに uv run を使用します
• または手動でインストールします：pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

「YOUTUBE_API_KEY environment variable not set」

• シェル、~/.claude/.env、またはローカルの .env で YOUTUBE_API_KEY を設定します

「HttpError 403: quotaExceeded」

• YouTube Data API には 1 日あたりのクォータがあります（デフォルトは 10,000 単位です）
• クォータがリセットされるまで待つか、クォータの引き上げを申請します
• スクリプトはレート制限されたリクエストを自動的に再試行します（指数バックオフを使用し、最大 3 回試行します）

「No transcript available」

• 動画で字幕が有効になっていない可能性があります
• 別の --language コードを試します
• 他の言語で自動生成された字幕が利用できる場合があります

参考資料

• references/youtube-data-api.md — YouTube Data API v3 のエンドポイント、クォータ、レスポンス構造