YouTube Data API v3 を curl + jq で呼び出します。ユーザーの OAuth ベアラートークンは $GOOGLE_YOUTUBE_TOKEN に格納されています。すべての呼び出しで Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN ヘッダーが必要です。ベース URL: https://www.googleapis.com/youtube/v3。
このトークンは常に youtube.readonly と id スコープ(openid email profile)を持ち、インストール時にユーザーがオプトインした場合は youtube.upload(動画公開)も含まれます。
レスポンスは標準的な JSON です。エラーは {"error": {"code": 401|403|..., "message": "..."}} として返されるため、そのまま表示してください。401 はトークン期限切れ、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...)を取得 — 上記のチャンネル呼び出しと同じ。
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}'
ページングするには、前のレスポンスの .nextPageToken を --data-urlencode "pageToken=$PAGE_TOKEN" として渡します。
動画の統計情報(視聴回数 / いいね数 / コメント数)
# カンマ区切りの 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 が必要)
公開前にユーザーに確認 — タイトル、公開設定、アップロードするファイルを表示してください。アップロードは 2 段階の再開可能フローです。メタデータで初期化 → PUT でバイト列を送信。
FILE="/path/to/video.mp4"
TITLE="マイタイトル"
DESC="概要説明"
# privacyStatus: public | unlisted | private
read -r -d '' META <<JSON
{"snippet":{"title":"$TITLE","description":"$DESC","categoryId":"22"},
"status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}}
JSON
# 1. 再開可能セッションを初期化 → 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 = 「People & Blogs」(安全なデフォルト値)。カスタムサムネイルを設定するには(ファイルの処理が完了している必要があります)、POST /upload/youtube/v3/thumbnails/set?videoId=VIDEO_ID を画像を指定して呼び出します。
注意点
- 割り当て量: Data API には割り当て量制限があります(デフォルト 10,000 ユニット/日)。
searchは 100 ユニット、uploadは約 1,600 ユニットを消費します。短時間に連続検索すると 1 日の割り当てを使い果たし、403 quotaExceededが返されることがあります。そのまま表示してください。 - 「自分の動画」エンドポイントはありません — 常にアップロードプレイリスト経由で取得してください。
searchの結果は結果整合性 — アップロードした直後の動画が検索結果に表示されるまで数分から数時間かかることがあります。代わりにアップロードプレイリストや ID で読み取ってください。- アップロードした動画は最初
uploaded/processing状態になり、処理が完了するまで統計情報は0です。