YouTube Data API v3 스킬
공식 YouTube Data API v3 문서를 기반으로 한 완전한 래퍼입니다.
설정
API 키 설정
# 옵션 1: 환경 변수 사용 (권장)
export YOUTUBE_API_KEY="YOUR_API_KEY_HERE"
# 옵션 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 tutorial" \
--max-results 25
# 시간별 필터 (지난주)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "machine learning" \
--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 nature" \
--video-definition high \
--type video
# 자막이 있는 동영상
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "TED talk" \
--video-caption closedCaption \
--type video
# 라이브 스트리밍 동영상
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "gaming" \
--event-type live \
--type video
# 지역별 필터
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "news" \
--region-code US \
--relevance-language en
# 동영상 길이별 필터
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "documentary" \
--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
동영상 Parts 참조
| Part | 포함 내용 |
|---|---|
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
# 핸들(@사용자 이름)로 가져오기
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
--for-handle "@Google" \
--parts snippet,statistics,brandingSettings
채널 Parts 참조
| Part | 포함 내용 |
|---|---|
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 artificial intelligence" \
--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 talk motivation" \
--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가 필요한 작업
다음 작업에는 사용자 인증(OAuth)이 필요하며, API 키만으로는 충분하지 않습니다.
- 동영상 업로드
- 동영상 메타데이터 업데이트
- 동영상 삭제
- 재생목록 관리
- 댓글 작성/삭제
- 평가 (좋아요/싫어요)
- 구독 관리
OAuth 설정은 추가 구성이 필요합니다. 자세한 내용은 YouTube Data API 문서를 참조하세요.
추가 팁
자주 사용되는 명령어 조합
# 1. 채널의 최신 동영상 찾기
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--channel-id "CHANNEL_ID" \
--order date \
--type video \
--max-results 10
# 2. 채널 검색
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "Python tutorials" \
--type channel \
--max-results 10
# 3. 가장 오래된 동영상 찾기 (날짜 오름차순)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
--query "JavaScript" \
--order date \
--type video
# 4. 특정 채널의 특정 재생목록 가져오기
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
--channel-id "CHANNEL_ID"
# 5. 재생목록의 모든 동영상 세부 정보 가져오기
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
--playlist-id "PLAYLIST_ID" \
--all-pages \
--output playlist_contents.json
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
--ids-from playlist_contents.json \
--parts snippet,statistics,contentDetails \
--output playlist_video_details.json
여러 API 키 사용
여러 API 키가 있는 경우, 스크립트를 실행하기 전에 YOUTUBE_API_KEY 환경 변수를 변경할 수 있습니다.
export YOUTUBE_API_KEY="SECOND_API_KEY"