# 유튜브 재생목록 조회 유튜브 공개 재생목록의 제목·채널·영상 수와 수록 영상 목록을 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/youtube_playlist 응답 필드 - `data` (object): 조회 데이터 - `data.playlist_id` (string): 재생목록 ID - `data.url` (string): 재생목록 주소 - `data.title` (string): 재생목록 제목 - `data.description` (string): 재생목록 설명 - `data.channel` (object): 채널 정보. 없으면 null null 허용. - `data.channel.id` (string): 채널 ID - `data.channel.name` (string): 채널 이름 - `data.channel.url` (string): 채널 주소 - `data.channel.handle` (string): 채널 핸들(@아이디). 없으면 null null 허용. - `data.video_count` (integer): 재생목록 전체 영상 수. 모르면 null null 허용. - `data.view_count` (integer): 재생목록 조회수. 모르면 null null 허용. - `data.modified_date` (string): 마지막 수정일 (YYYY-MM-DD). 모르면 null null 허용. - `data.count` (integer): 이번 응답에 담긴 영상 수 - `data.videos` (array): 영상 목록. 항목 형식은 유튜브 검색 결과의 video·short 항목과 같습니다. - `data.videos[].type` (string): 아래 하위 항목을 확인하세요. - `data.videos[].id` (string): 아래 하위 항목을 확인하세요. - `data.videos[].url` (string): 아래 하위 항목을 확인하세요. - `data.videos[].title` (string): 아래 하위 항목을 확인하세요. - `data.videos[].description` (undefined): 아래 하위 항목을 확인하세요. null 허용. - `data.videos[].duration` (integer): 아래 하위 항목을 확인하세요. - `data.videos[].view_count` (integer): 아래 하위 항목을 확인하세요. - `data.videos[].live_status` (undefined): 아래 하위 항목을 확인하세요. null 허용. - `data.videos[].published_at` (undefined): 아래 하위 항목을 확인하세요. null 허용. - `data.videos[].channel` (object): 아래 하위 항목을 확인하세요. - `data.videos[].channel.id` (string): 아래 하위 항목을 확인하세요. - `data.videos[].channel.name` (string): 아래 하위 항목을 확인하세요. - `data.videos[].channel.url` (string): 아래 하위 항목을 확인하세요. - `data.videos[].channel.handle` (string): 아래 하위 항목을 확인하세요. - `data.videos[].thumbnail` (string): 아래 하위 항목을 확인하세요. - `data.success` (integer): 과금 여부0: 실패1: 성공 - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부 - `api.cost` (integer): API 호출 요금 - `api.pl_id` (integer): API 결제 로그 ID - `api.ms` (integer): API 응답 시간 ## API 요청: POST /rest/youtube_playlist ### 입력 - `url` (string, 필수): 재생목록 URL(list= 포함) 또는 재생목록 ID (예: PL...) - `count` (integer, 선택): 가져올 영상 수 1~200 (기본 50) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "playlist_id": { "type": "string", "description": "재생목록 ID" }, "url": { "type": "string", "description": "재생목록 주소" }, "title": { "type": "string", "description": "재생목록 제목" }, "description": { "type": "string", "description": "재생목록 설명" }, "channel": { "type": "object", "properties": { "id": { "type": "string", "description": "채널 ID" }, "name": { "type": "string", "description": "채널 이름" }, "url": { "type": "string", "description": "채널 주소" }, "handle": { "type": "string", "description": "채널 핸들(@아이디). 없으면 null", "nullable": true } }, "description": "채널 정보. 없으면 null", "nullable": true }, "video_count": { "type": "integer", "description": "재생목록 전체 영상 수. 모르면 null", "nullable": true }, "view_count": { "type": "integer", "description": "재생목록 조회수. 모르면 null", "nullable": true }, "modified_date": { "type": "string", "description": "마지막 수정일 (YYYY-MM-DD). 모르면 null", "nullable": true }, "count": { "type": "integer", "description": "이번 응답에 담긴 영상 수" }, "videos": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "description": { "nullable": true }, "duration": { "type": "integer" }, "view_count": { "type": "integer" }, "live_status": { "nullable": true }, "published_at": { "nullable": true }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" } } }, "thumbnail": { "type": "string" } } }, "description": "영상 목록. 항목 형식은 유튜브 검색 결과의 video·short 항목과 같습니다." }, "success": { "type": "integer", "description": "과금 여부0: 실패1: 성공" } }, "description": "조회 데이터" }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 서버 정상 응답 여부" }, "cost": { "type": "integer", "description": "API 호출 요금" }, "pl_id": { "type": "integer", "description": "API 결제 로그 ID" }, "ms": { "type": "integer", "description": "API 응답 시간" } }, "description": "API 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "data": { "playlist_id": "PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH", "url": "https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH", "title": "Coding Challenges", "description": "Watch me take on some viewer submitted coding challenges.", "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "video_count": 246, "view_count": 2718296, "modified_date": "2026-04-27", "count": 2, "videos": [ { "type": "video", "id": "17WoOqgXsRM", "url": "https://www.youtube.com/watch?v=17WoOqgXsRM", "title": "Coding Challenge 1: Starfield Simulation", "description": null, "duration": 834, "view_count": 1300000, "live_status": null, "published_at": null, "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "thumbnail": "https://i.ytimg.com/vi/17WoOqgXsRM/hqdefault.jpg" }, { "type": "video", "id": "LG8ZK-rRkXo", "url": "https://www.youtube.com/watch?v=LG8ZK-rRkXo", "title": "Coding Challenge #2: Menger Sponge Fractal", "description": null, "duration": 799, "view_count": 410000, "live_status": null, "published_at": null, "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "thumbnail": "https://i.ytimg.com/vi/LG8ZK-rRkXo/hqdefault.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595635, "ms": 3210 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/youtube_playlist' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'url=https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH' \ --form-string 'count=2' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("url", "https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH"); form.append("count", "2"); const response = await fetch("https://apick.app/rest/youtube_playlist", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("url", (None, "https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH")), ("count", (None, "2")), ] response = requests.request("POST", "https://apick.app/rest/youtube_playlist", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH', 'count' => '2', ]; $curl = curl_init('https://apick.app/rest/youtube_playlist'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 ## 상세 기능·요금 Method URL POST https://apick.app/rest/youtube_playlist API 호출 요청 요청하기 Key Value url count 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터 playlist_id String 재생목록 ID url String 재생목록 주소 title String 재생목록 제목 description String 재생목록 설명 channel Object 채널 정보. 없으면 null id String 채널 ID name String 채널 이름 url String 채널 주소 handle String 채널 핸들(@아이디). 없으면 null video_count Integer 재생목록 전체 영상 수. 모르면 null view_count Integer 재생목록 조회수. 모르면 null modified_date String 마지막 수정일 (YYYY-MM-DD). 모르면 null count Integer 이번 응답에 담긴 영상 수 videos Array 영상 목록. 항목 형식은 유튜브 검색 결과의 video·short 항목과 같습니다. success Integer 과금 여부0: 실패1: 성공 api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer API 호출 요금 ms Integer API 응답 시간 pl_id Integer API 결제 로그 ID ## 상세 코드·정책 오류 HTTP 상태 코드 HTTP 상황 설명 400 입력 오류 재생목록 주소·ID와 count 값을 확인하세요. 404 재생목록 없음 삭제·비공개 재생목록이거나 잘못된 주소입니다. 408 시간 초과 처리 시간이 초과됐습니다. 과금하지 않습니다. 424 조회 불가 일시적으로 가져오지 못했습니다. 잠시 후 다시 시도해 주세요. 실패한 호출은 과금하지 않습니다. ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "playlist_id": "PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH", "url": "https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZiZxtDDRCi6uhfTH4FilpH", "title": "Coding Challenges", "description": "Watch me take on some viewer submitted coding challenges.", "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "video_count": 246, "view_count": 2718296, "modified_date": "2026-04-27", "count": 2, "videos": [ { "type": "video", "id": "17WoOqgXsRM", "url": "https://www.youtube.com/watch?v=17WoOqgXsRM", "title": "Coding Challenge 1: Starfield Simulation", "description": null, "duration": 834, "view_count": 1300000, "live_status": null, "published_at": null, "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "thumbnail": "https://i.ytimg.com/vi/17WoOqgXsRM/hqdefault.jpg" }, { "type": "video", "id": "LG8ZK-rRkXo", "url": "https://www.youtube.com/watch?v=LG8ZK-rRkXo", "title": "Coding Challenge #2: Menger Sponge Fractal", "description": null, "duration": 799, "view_count": 410000, "live_status": null, "published_at": null, "channel": { "id": "UCvjgXvBlbQiydffZU7m1_aw", "name": "The Coding Train", "url": "https://www.youtube.com/channel/UCvjgXvBlbQiydffZU7m1_aw", "handle": "@TheCodingTrain" }, "thumbnail": "https://i.ytimg.com/vi/LG8ZK-rRkXo/hqdefault.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595635, "ms": 3210 } }