YouTube Playlist Videos
YouTube 재생목록 동영상은 공개 재생목록에 묶여 있는 항목으로, 동영상 식별 정보, 제목, 채널 컨텍스트, 썸네일, 재생 시간, 재생목록 출처 정보를 담고 있습니다. 이러한 레코드는 재생목록 카탈로그 작성, 시리즈 인덱싱, 콘텐츠 검토, 동영상 링크 보강에 활용할 수 있습니다.
YouTube Playlist Videos API 주요 기능
- 여러 재생목록 URL·ID 입력작업 하나에서 공개 재생목록 URL 또는 재생목록 ID를 하나 이상 처리하며, results_limit은 확인된 재생목록마다 따로 적용됩니다.
- 정규화된 동영상 카탈로그 행동영상 ID, 제목, 정식 URL, 채널 정보, 썸네일 1개, 초 단위 재생 시간, 수집 시각을 일관된 구조로 반환합니다.
- 재생목록·소유자 출처 정보재생목록 ID, 재생목록 제목, 읽기 쉬운 재생 시간 텍스트를 보존하며, 동영상 행에 자체 채널 필드가 없으면 재생목록 소유자 컨텍스트도 함께 보존합니다.
YouTube Playlist Videos API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | list 쿼리 값이 들어 있는 공개 재생목록 URL 또는 재생목록 ID를 하나 이상 지정하며, 쉼표 또는 줄바꿈으로 구분합니다. |
results_limit | 선택 | 각 재생목록에서 반환된 동영상 배열 중 보관할 최대 레코드 수로, 기본값은 100이며 10~2,000의 정수를 받습니다. |
YouTube Playlist Videos API 사용 방법
알고 있는 공개 재생목록 참조를 비동기 작업으로 제출하고, 작업이 성공하면 저장된 정규화 동영상 행을 페이지 단위로 읽습니다.
- list 쿼리 값이 들어 있는 공개 재생목록 URL 또는 재생목록 ID를 하나 이상 준비하고, 중복된 참조는 제거합니다.
- urls와 선택 항목인 results_limit(10~2,000)을 /v1/youtube/playlist-videos로 POST하고, 반환된 task_id를 저장합니다.
- 작업 status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고 results.has_more가 true인 동안 results.next_cursor로 이어서 가져오며, 재생목록 ID와 동영상 ID를 원본 집합과 대조합니다.
curl -X POST "https://api.socq.ai/v1/youtube/playlist-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.youtube.com/playlist?list=PLP32wGpgzmIlInfgKVFfCwVsxgGqZNIiS"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueYouTube Playlist Videos API 추천 활용 사례
- 공개 재생목록 인벤토리: 선택한 공개 재생목록의 동영상 ID, 제목, URL, 채널 정보, 썸네일, 재생 시간, 재생목록 출처 정보를 구조화된 인벤토리로 구축합니다.
- 강의·시리즈 인덱싱: 재생목록 제목을 동영상 제목, 채널 컨텍스트, 재생 시간, 원본 링크와 함께 색인하여 공개 강의, 강연, 에피소드형 모음을 정리합니다.
- 동영상 보강용 시드 목록: 반환된 정식 동영상 URL과 ID를 중복 제거된 큐로 삼아, 별도의 상세 조회·스크립트·리뷰·보관 워크플로에 활용합니다.
YouTube Playlist Videos API 활용 팁
- 재생목록 ID 또는 list 쿼리 값이 채워진 URL 중 하나를 사용하세요. URL의 다른 부분은 재생목록 확인에 쓰이지 않으며, list가 없는 URL은 건너뜁니다.
- results_limit은 반환된 첫 동영상 배열에 대한 재생목록별 상한으로 취급하세요. 대형 재생목록을 깊이 추출한다는 보장이 아닙니다.
- 정확히 같은 문자열만 중복으로 제거되고 같은 재생목록의 URL 변형은 반복 작업을 일으킬 수 있으므로, 배치로 보내기 전에 재생목록마다 표기를 하나로 통일하세요.
- 비공개·삭제·제한·숨김·형식 오류·접근 불가 항목은 빠질 수 있으므로, 반환된 extra.playlist_id와 동영상 id 값을 입력 집합과 비교하세요.
- 레코드 계보는 collected_at으로 관리하세요. metrics가 비어 있고 created_at이 null이므로, 게시일이나 참여도가 필요하면 동영상 상세를 별도로 요청하세요.
관련 API
YouTube Playlist Videos API 외에 YouTube의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- YouTube Channel Videos API — 채널 URL에서 쇼츠와 라이브 방송을 제외한 일반 공개 동영상을 수집합니다.
- YouTube Comments API — 공개 댓글, 작성자, 참여도, 원본 동영상, 대화 맥락을 수집합니다.
- YouTube Transcripts API — 제공되는 일반 텍스트 스크립트를 가져오며, 언어를 선택할 수 있습니다.
- YouTube Videos API — 알고 있는 동영상 또는 쇼츠 URL의 메타데이터, 썸네일, 길이, 참여도를 가져옵니다.
- YouTube Shorts API — 채널별로 공개 쇼츠, 썸네일, 길이, 게시 정보, 참여도를 수집합니다.
- YouTube Channel Live Videos API — 채널의 라이브 영역에 노출된 공개 방송 기록을 수집하며, 출처 맥락과 공개된 지표를 포함합니다.
- YouTube Channels API
- YouTube Search API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Hashtag Search API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Channel Search API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API