Communitygithub.com

YouTube Data API v3 완전 래퍼 (Claude Skills)

YouTube Data API v3의 완전한 래퍼입니다. 동영상 검색, 동영상/채널/재생목록 세부 정보 조회, 댓글 확인, 자막 다운로드 등을 지원합니다. 시간, 조회수, 평점 등 다양한 기준으로 필터링 및 정렬이 가능합니다.

YouTube Data API v3 완전 래퍼 (Claude Skills)란 무엇인가요?

이 스킬은 Claude Code, Cursor, Codex 등의 AI 에이전트가 YouTube Data API v3와 완전히 상호작용할 수 있도록 하는 포괄적인 래퍼입니다. 공식 YouTube Data API v3 문서를 기반으로 구축되었으며, 개발자와 AI 에이전트가 복잡한 API 호출을 직접 다루지 않고도 동영상 검색, 채널 및 재생목록 세부 정보 조회, 댓글 분석, 자막 다운로드 등의 작업을 간단한 CLI 명령어로 수행할 수 있게 해줍니다. 주요 기능으로는 키워드, 게시일, 조회수, 평점 등 다양한 기준으로 동영상을 검색하고 필터링하는 기능, 단일 또는 배치로 동영상의 상세한 통계 및 메타데이터를 가져오는 기능, 채널 구독자 수와 같은 통계를 포함한 전체 정보를 조회하는 기능, 재생목록과 그 목록을 관리하는 기능, 동영상 댓글을 검색하고 분석하는 기능, 그리고 OAuth 인증이 필요한 경우를 위해 yt-dlp를 대체 방법으로 제공하는 자막 다운로드 기능이 포함됩니다. 이 스킬은 JSON, CSV 등 다양한 출력 형식을 지원하며, 대규모 데이터셋을 위한 페이지네이션을 처리하고, 사용자가 API 할당량을 효과적으로 모니터링하고 최적화할 수 있도록 도와줍니다. 환경 변수(`YOUTUBE_API_KEY`)를 통해 API 키를 설정하며, Google Cloud Console에서 키를 발급받아야 합니다. 할당량 비용은 읽기 작업 1단위, 검색 요청 100단위 등으로 투명하게 공개되어 있어 사용자가 비용을 예측할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yrzhe/claude-skills/tree/HEAD/plugins/youtube-data-api/skills/youtube-data-api

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 키 얻기

  1. Google Cloud Console로 이동합니다.
  2. 새 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
  3. YouTube Data API v3를 사용 설정합니다.
  4. 사용자 인증 정보 → API 키를 만듭니다.
  5. (선택 사항) 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요청이 너무 많음요청 빈도 줄이기

할당량 최적화 팁

  1. fields 매개변수를 사용하여 필요한 필드만 요청
  2. 배치 요청을 위해 쉼표로 구분된 ID 목록 사용
  3. 결과 캐싱으로 중복 요청 방지
  4. 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"

참고 자료

관련 스킬