使用 curl + jq 呼叫 YouTube Data API v3。使用者的 OAuth bearer token 位於 $GOOGLE_YOUTUBE_TOKEN;每次呼叫都需要將其作為 Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN。Base URL:https://www.googleapis.com/youtube/v3。
該 token 始終攜帶 youtube.readonly 以及身分驗證範圍(openid email profile);如果使用者在安裝時選擇加入,則還會攜帶 youtube.upload(發布影片)。
回應為標準 JSON;失敗時會顯示為 {"error": {"code": 401|403|..., "message": "..."}} —— 請逐字顯示該錯誤。401 表示 token 過期,使用者必須重新連線 YouTube 連接器。上傳時出現 403 insufficientPermissions 表示使用者未授予 youtube.upload 權限;請要求他們重新連線並勾選上傳方塊。
始終從頻道檢查開始,以確認連線正常並了解你正在操作哪個頻道。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true" \
| jq '.items[0] | {title: .snippet.title, subs: .statistics.subscriberCount, views: .statistics.viewCount, uploads: .contentDetails.relatedPlaylists.uploads}'
搜尋 YouTube
# 公開搜尋(任何影片)。type 可以是 video|channel|playlist。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
--data-urlencode "q=ai video automation" \
--data-urlencode "part=snippet" \
--data-urlencode "type=video" \
--data-urlencode "maxResults=10" \
-G "https://www.googleapis.com/youtube/v3/search" \
| jq '.items[] | {videoId: .id.videoId, title: .snippet.title, channel: .snippet.channelTitle, published: .snippet.publishedAt}'
加入 --data-urlencode "order=date|viewCount|rating|relevance" 來排序,或 --data-urlencode "publishedAfter=2026-01-01T00:00:00Z" 來設定時間區間。
查看我的上傳影片
YouTube 沒有直接的「列出我的影片」呼叫——請讀取頻道的 上傳播放清單,然後進行分頁。
# 1. 取得上傳播放清單的 ID(UU... )——與上方 channels 呼叫相同。
UPLOADS=$(curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=contentDetails&mine=true" \
| jq -r '.items[0].contentDetails.relatedPlaylists.uploads')
# 2. 列出最近的上傳內容(每頁 50 個;請跟隨 .nextPageToken 取得更多)。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/playlistItems" \
--data-urlencode "part=snippet,contentDetails" \
--data-urlencode "playlistId=$UPLOADS" \
--data-urlencode "maxResults=50" \
| jq '.items[] | {videoId: .contentDetails.videoId, title: .snippet.title, published: .snippet.publishedAt}'
使用 --data-urlencode "pageToken=$PAGE_TOKEN" 傳入前一次回應中的 .nextPageToken 來進行分頁。
影片統計資料(觀看數 / 按讚數 / 留言數)
# 接受以逗號分隔的 ID 清單。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/videos" \
--data-urlencode "part=snippet,statistics,status" \
--data-urlencode "id=VIDEO_ID_1,VIDEO_ID_2" \
| jq '.items[] | {title: .snippet.title, views: .statistics.viewCount, likes: .statistics.likeCount, comments: .statistics.commentCount, privacy: .status.privacyStatus}'
讀取影片的留言
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/commentThreads" \
--data-urlencode "part=snippet" \
--data-urlencode "videoId=VIDEO_ID" \
--data-urlencode "maxResults=20" \
--data-urlencode "order=relevance" \
| jq '.items[] | .snippet.topLevelComment.snippet | {author: .authorDisplayName, text: .textDisplay, likes: .likeCount}'
上傳影片(需要 youtube.upload)
在發布前先與使用者確認——顯示即將上傳的標題、隱私設定和檔案。上傳是一個兩步驟的可恢復流程:初始化中繼資料 → PUT 位元組。
FILE="/path/to/video.mp4"
TITLE="My title"
DESC="My description"
# privacyStatus: public | unlisted | private
read -r -d '' META <<JSON
{"snippet":{"title":"$TITLE","description":"$DESC","categoryId":"22"},
"status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}}
JSON
# 1. 初始化可恢復 session -> 從 Location 標頭擷取上傳 URL。
UPLOAD_URL=$(curl -sS -D - -o /dev/null \
-H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "X-Upload-Content-Type: video/*" \
-X POST "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status" \
-d "$META" | tr -d '\r' | awk '/^[Ll]ocation:/{print $2}')
# 2. 上傳位元組 -> 回傳已建立的影片資源(包含 .id)。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: video/*" \
-X PUT --upload-file "$FILE" "$UPLOAD_URL" \
| jq '{id: .id, url: ("https://www.youtube.com/watch?v=" + .id), privacy: .status.privacyStatus}'
categoryId 22 =「人物與網誌」(安全的預設值)。要設定自訂縮圖(需要先處理檔案),請使用該圖片呼叫 POST /upload/youtube/v3/thumbnails/set?videoId=VIDEO_ID。
注意事項
- 配額: Data API 有配額限制(預設為每天 10,000 單位)。一個
search花費 100 單位;一個upload花費約 1,600 單位。大量搜尋可能會耗盡每日配額 →403 quotaExceeded;請清楚地顯示此訊息。 - 沒有「我的影片」端點——始終透過上傳播放清單來操作。
search結果是最終一致性的——新上傳的影片可能需要幾分鐘到幾小時才會出現在search結果中;請改由上傳播放清單或直接以 ID 讀取。- 上傳的影片會先處於
uploaded/processing狀態;統計資料在處理完成前會顯示為0。