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 金鑰
- 前往 Google Cloud Console
- 建立新專案或選擇現有專案
- 啟用 YouTube Data API v3
- 建立憑證 → API 金鑰
- (可選)將 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 | 請求次數過多 | 降低請求頻率 |
配額最佳化建議
- 使用
fields參數僅請求需要的欄位 - 批次請求使用逗號分隔的 ID 清單
- 快取結果以避免重複請求
- 使用 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 |
|---|---|
| YouTube | UCBR8-60_B28GngBQva5T2kQ |
| Google Developers | UC_x5XG1OV2P6uZZ5FSM9Ttw |
UCK8sQmJBp8GCxrOtXWBpyEA |
環境變數
| 變數 | 說明 |
|---|---|
YOUTUBE_API_KEY | API 金鑰 |
YOUTUBE_CLIENT_ID | OAuth 用戶端 ID |
YOUTUBE_CLIENT_SECRET | OAuth 用戶端密鑰 |
yt-dlp 替代工具
- yt-dlp:功能完整的 YouTube 下載器
- 影片串流品質:
yt-dlp -f "bestvideo+bestaudio" "URL" - 僅音訊:
yt-dlp -f bestaudio --extract-audio --audio-format mp3 "URL"