# 유튜브 검색 키워드로 유튜브 영상·쇼츠·채널·재생목록을 검색합니다. 정렬(관련도·업로드일·조회수·평점)과 업로드 시기·종류·길이 조건을 지정할 수 있습니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/youtube_search 응답 필드 - `data` (object): 조회 데이터 - `data.query` (string): 검색어 - `data.count` (integer): 결과 수 - `data.results` (array): 검색 결과 목록 - `data.results[].type` (string): 항목 종류video: 영상short: 쇼츠channel: 채널playlist: 재생목록 - `data.results[].id` (string): 영상 ID(11자리)·채널 ID(UC…)·재생목록 ID - `data.results[].url` (string): 항목 주소 - `data.results[].title` (string): 제목(채널은 채널 이름) - `data.results[].description` (string): 설명 일부. 없으면 null null 허용. - `data.results[].duration` (integer): 영상 길이(초). 영상·쇼츠만, 모르면 null null 허용. - `data.results[].view_count` (integer): 조회수. 영상·쇼츠만, 모르면 null null 허용. - `data.results[].live_status` (string): 라이브 상태(is_live·was_live 등). 일반 영상은 null null 허용. - `data.results[].published_at` (string): 게시 시각(ISO 8601). 목록에서 제공하지 않으면 null null 허용. - `data.results[].channel` (object): 올린 채널 {id, name, url, handle}. 영상·쇼츠·재생목록 - `data.results[].channel.id` (string): 아래 하위 항목을 확인하세요. - `data.results[].channel.name` (string): 아래 하위 항목을 확인하세요. - `data.results[].channel.url` (string): 아래 하위 항목을 확인하세요. - `data.results[].channel.handle` (string): 아래 하위 항목을 확인하세요. - `data.results[].thumbnail` (string): 대표 썸네일 주소 - `data.results[].handle` (string): 채널 핸들. 채널 항목만 - `data.results[].follower_count` (integer): 구독자 수. 채널 항목만 - `data.results[].is_verified` (boolean): 인증 채널 여부. 채널 항목만 - `data.results[].video_count` (integer): 영상 수. 재생목록 항목만, 모르면 null null 허용. - `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_search ### 입력 - `query` (string, 필수): 검색어 (1~200자) - `count` (integer, 선택): 결과 수 1~50 (기본 10) - `sort` (string, 선택): 정렬: relevance(관련도, 기본)·date(업로드일)·views(조회수)·rating(평점) 허용값: relevance, date, views, rating - `type` (string, 선택): 결과 종류 (기본 any) 허용값: any, video, channel, playlist, movie - `upload_date` (string, 선택): 업로드 시기 (기본 any) 허용값: any, hour, today, week, month, year - `duration` (string, 선택): 길이: short(4분 미만)·medium(4~20분)·long(20분 초과) 허용값: any, short, medium, long ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "query": { "type": "string", "description": "검색어" }, "count": { "type": "integer", "description": "결과 수" }, "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "항목 종류video: 영상short: 쇼츠channel: 채널playlist: 재생목록" }, "id": { "type": "string", "description": "영상 ID(11자리)·채널 ID(UC…)·재생목록 ID" }, "url": { "type": "string", "description": "항목 주소" }, "title": { "type": "string", "description": "제목(채널은 채널 이름)" }, "description": { "type": "string", "nullable": true, "description": "설명 일부. 없으면 null" }, "duration": { "type": "integer", "description": "영상 길이(초). 영상·쇼츠만, 모르면 null", "nullable": true }, "view_count": { "type": "integer", "description": "조회수. 영상·쇼츠만, 모르면 null", "nullable": true }, "live_status": { "nullable": true, "type": "string", "description": "라이브 상태(is_live·was_live 등). 일반 영상은 null" }, "published_at": { "nullable": true, "type": "string", "description": "게시 시각(ISO 8601). 목록에서 제공하지 않으면 null" }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" } }, "description": "올린 채널 {id, name, url, handle}. 영상·쇼츠·재생목록" }, "thumbnail": { "type": "string", "description": "대표 썸네일 주소" }, "handle": { "type": "string", "description": "채널 핸들. 채널 항목만" }, "follower_count": { "type": "integer", "description": "구독자 수. 채널 항목만" }, "is_verified": { "type": "boolean", "description": "인증 채널 여부. 채널 항목만" }, "video_count": { "type": "integer", "description": "영상 수. 재생목록 항목만, 모르면 null", "nullable": true } } }, "description": "검색 결과 목록" }, "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": { "query": "파이썬 기초 강좌", "count": 2, "results": [ { "type": "video", "id": "kWiCuklohdY", "url": "https://www.youtube.com/watch?v=kWiCuklohdY", "title": "파이썬 코딩 무료 강의 (기본편)", "description": "파이썬 무료 강의 (기본편)입니다.", "duration": 21639, "view_count": 6500000, "live_status": null, "published_at": null, "channel": { "id": "UC7iAOLiALt2rtMVAWWl4pnw", "name": "나도코딩", "url": "https://www.youtube.com/channel/UC7iAOLiALt2rtMVAWWl4pnw", "handle": "@nadocoding" }, "thumbnail": "https://i.ytimg.com/vi/kWiCuklohdY/hq720.jpg" }, { "type": "video", "id": "ftQZo7XaTOA", "url": "https://www.youtube.com/watch?v=ftQZo7XaTOA", "title": "최신 파이썬 코딩 무료 강의", "description": null, "duration": 31120, "view_count": 620822, "live_status": null, "published_at": null, "channel": { "id": "UCQNE2JmbasNYbjGAcuBiRRg", "name": "조코딩 JoCoding", "url": "https://www.youtube.com/channel/UCQNE2JmbasNYbjGAcuBiRRg", "handle": "@jocoding" }, "thumbnail": "https://i.ytimg.com/vi/ftQZo7XaTOA/hq720.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_search' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'query=파이썬 기초 강좌' \ --form-string 'count=2' \ --form-string 'type=video' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("query", "파이썬 기초 강좌"); form.append("count", "2"); form.append("type", "video"); const response = await fetch("https://apick.app/rest/youtube_search", { 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 = [ ("query", (None, "파이썬 기초 강좌")), ("count", (None, "2")), ("type", (None, "video")), ] response = requests.request("POST", "https://apick.app/rest/youtube_search", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '파이썬 기초 강좌', 'count' => '2', 'type' => 'video', ]; $curl = curl_init('https://apick.app/rest/youtube_search'); 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_search API 호출 요청 요청하기 Key Value query count sort type upload_date duration 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터 query String 검색어 count Integer 결과 수 results Array 검색 결과 목록 type String 항목 종류video: 영상short: 쇼츠channel: 채널playlist: 재생목록 id String 영상 ID(11자리)·채널 ID(UC…)·재생목록 ID url String 항목 주소 title String 제목(채널은 채널 이름) description String 설명 일부. 없으면 null duration Integer 영상 길이(초). 영상·쇼츠만, 모르면 null view_count Integer 조회수. 영상·쇼츠만, 모르면 null live_status String 라이브 상태(is_live·was_live 등). 일반 영상은 null published_at String 게시 시각(ISO 8601). 목록에서 제공하지 않으면 null channel Object 올린 채널 {id, name, url, handle}. 영상·쇼츠·재생목록 handle String 채널 핸들. 채널 항목만 follower_count Integer 구독자 수. 채널 항목만 is_verified Boolean 인증 채널 여부. 채널 항목만 video_count Integer 영상 수. 재생목록 항목만, 모르면 null thumbnail String 대표 썸네일 주소 success Integer 과금 여부0: 실패1: 성공 api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer API 호출 요금 ms Integer API 응답 시간 pl_id Integer API 결제 로그 ID ## 상세 코드·정책 오류 HTTP 상태 코드 HTTP 상황 설명 400 입력 오류 query, count, sort, type, upload_date, duration 값을 확인하세요. 408 시간 초과 처리 시간이 초과됐습니다. 과금하지 않습니다. 424 조회 불가 일시적으로 가져오지 못했습니다. 잠시 후 다시 시도해 주세요. 실패한 호출은 과금하지 않습니다. ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "query": "파이썬 기초 강좌", "count": 2, "results": [ { "type": "video", "id": "kWiCuklohdY", "url": "https://www.youtube.com/watch?v=kWiCuklohdY", "title": "파이썬 코딩 무료 강의 (기본편)", "description": "파이썬 무료 강의 (기본편)입니다.", "duration": 21639, "view_count": 6500000, "live_status": null, "published_at": null, "channel": { "id": "UC7iAOLiALt2rtMVAWWl4pnw", "name": "나도코딩", "url": "https://www.youtube.com/channel/UC7iAOLiALt2rtMVAWWl4pnw", "handle": "@nadocoding" }, "thumbnail": "https://i.ytimg.com/vi/kWiCuklohdY/hq720.jpg" }, { "type": "video", "id": "ftQZo7XaTOA", "url": "https://www.youtube.com/watch?v=ftQZo7XaTOA", "title": "최신 파이썬 코딩 무료 강의", "description": null, "duration": 31120, "view_count": 620822, "live_status": null, "published_at": null, "channel": { "id": "UCQNE2JmbasNYbjGAcuBiRRg", "name": "조코딩 JoCoding", "url": "https://www.youtube.com/channel/UCQNE2JmbasNYbjGAcuBiRRg", "handle": "@jocoding" }, "thumbnail": "https://i.ytimg.com/vi/ftQZo7XaTOA/hq720.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595635, "ms": 3210 } }