Communitygithub.com

Yrzhe/claude-skills

YouTube Data API v3 完整包裝 - 搜尋影片、取得影片/頻道/播放清單詳細資料、取得留言、下載字幕等。支援按時間/觀看次數/評分等條件進行篩選與排序。

claude-skills 是什麼?

此技能為 YouTube Data API v3 的完整命令列包裝,讓 AI 代理能透過 Python 腳本直接與 YouTube 資料互動。它支援廣泛的操作,包括影片搜尋(可依日期、觀看次數、評分等排序)、取得個別影片或頻道詳細資料、管理和瀏覽播放清單、擷取留言串,以及列出或下載字幕(後者需要 OAuth 驗證,也提供 yt-dlp 作為替代方案)。此技能針對 Claude Code 設計,透過環境變數或組態檔進行設定,並內建配額管理,以防超出每日 10,000 個單位的限制。輸出格式包括 JSON、CSV 和簡潔文字,並支援分頁以處理大型資料集,使其成為內容研究、頻道分析、趨勢監控以及留言或字幕處理等工作的強大工具。

相容平台✓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="您的API金鑰"

# 選項 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

配額限制

操作類型配額成本(單位)
讀取操作(list)1
搜尋請求100
寫入操作(insert/update/delete)50
影片上傳1600

預設每日配額:10,000 單位


核心功能

1. 搜尋影片(Search)

配額成本:100 單位/請求

# 基本搜尋
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python 教學" \
    --max-results 25

# 依時間篩選(上週)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "機器學習" \
    --published-after "7d" \
    --type video

# 依觀看次數排序
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "React hooks" \
    --order viewCount \
    --type video

# 僅 HD 影片
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "4K 自然風景" \
    --video-definition high \
    --type video

# 有字幕的影片
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "TED 演講" \
    --video-caption closedCaption \
    --type video

# 直播中的影片
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "遊戲" \
    --event-type live \
    --type video

# 依區域篩選
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "新聞" \
    --region-code US \
    --relevance-language en

# 依影片長度篩選
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "紀錄片" \
    --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(HD), standard(SD)
--video-caption字幕closedCaption(有字幕), none(無字幕)
--video-dimension維度2d, 3d
--event-type直播狀態live(直播中), completed(已結束), upcoming(即將開始)
--channel-id限定頻道頻道 ID
--safe-search安全搜尋none, moderate, strict

2. 取得影片詳細資料(Videos)

配額成本: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. 取得頻道資訊(Channels)

配額成本: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

# 依處理名稱(@username)取得
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. 取得播放清單(Playlists)

配額成本: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. 取得播放清單影片(PlaylistItems)

配額成本: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. 取得留言(Comments & CommentThreads)

配額成本: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. 取得字幕(Captions)

配額成本:1 單位/請求(list),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. 取得影片分類(VideoCategories)

配額成本: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 人工智慧" \
    --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 演講 勵志" \
    --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. 使用 ETags檢查資源是否已更新
# 僅取得需要的欄位(減少回應大小)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "VIDEO_ID" \
    --fields "items(id,snippet(title,channelTitle),statistics(viewCount))"

需要 OAuth 的操作

以下操作需要使用者授權(僅 API 金鑰不足):

  • 上傳影片
  • 更新影片中繼資料
  • 刪除影片
  • 管理播放清單
  • 留言/回覆
  • 下載字幕

附錄

常用頻道 ID

頻道ID
YouTubeUCBR8-60_B28GngBQva5T2kQ
Google DevelopersUC_x5XG1OV2P6uZZ5FSM9Ttw
GoogleUCK8sQmJBp8GCxrOtXWBpyEA

環境變數

變數說明
YOUTUBE_API_KEYAPI 金鑰
YOUTUBE_CLIENT_IDOAuth 用戶端 ID
YOUTUBE_CLIENT_SECRETOAuth 用戶端密鑰

yt-dlp 替代工具

  • yt-dlp:功能完整的 YouTube 下載器
  • 影片串流品質:yt-dlp -f "bestvideo+bestaudio" "URL"
  • 僅音訊:yt-dlp -f bestaudio --extract-audio --audio-format mp3 "URL"

相關技能