YouTube Data API v3를 curl + jq로 호출합니다. 사용자의 OAuth bearer 토큰은 $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 → 토큰 만료, 사용자가 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에는 "내 동영상 목록"을 직접 가져오는 호출이 없습니다. 채널의 uploads 재생목록을 읽은 후 해당 항목을 페이지네이션합니다.
# 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}'
이전 응답의 .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="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. 재개 가능 세션 초기화 -> 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입니다.