# 유튜브 해시태그 영상 조회 유튜브 해시태그 페이지에 올라온 영상 목록을 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/youtube_hashtag 응답 필드 - `data` (object): 조회 데이터 - `data.hashtag` (string): 조회한 해시태그 - `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` (undefined): 아래 하위 항목을 확인하세요. null 허용. - `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_hashtag ### 입력 - `hashtag` (string, 필수): 해시태그 (# 생략 가능, 예: kpop) - `count` (integer, 선택): 가져올 영상 수 1~100 (기본 30) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "hashtag": { "type": "string", "description": "조회한 해시태그" }, "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": { "nullable": true } } }, "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": { "hashtag": "kpop", "count": 1, "videos": [ { "type": "video", "id": "yebNIHKAC4A", "url": "https://www.youtube.com/watch?v=yebNIHKAC4A", "title": "“Golden” Official Lyric Video | KPop Demon Hunters", "description": null, "duration": 199, "view_count": 1761885143, "live_status": null, "published_at": null, "channel": { "id": "UCnLuLSV-Oi0ctqjxGgxFlmg", "name": "Sony Pictures Animation", "url": "https://www.youtube.com/channel/UCnLuLSV-Oi0ctqjxGgxFlmg", "handle": null }, "thumbnail": "https://i.ytimg.com/vi/yebNIHKAC4A/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_hashtag' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'hashtag=kpop' \ --form-string 'count=1' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("hashtag", "kpop"); form.append("count", "1"); const response = await fetch("https://apick.app/rest/youtube_hashtag", { 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 = [ ("hashtag", (None, "kpop")), ("count", (None, "1")), ] response = requests.request("POST", "https://apick.app/rest/youtube_hashtag", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'kpop', 'count' => '1', ]; $curl = curl_init('https://apick.app/rest/youtube_hashtag'); 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_hashtag API 호출 요청 요청하기 Key Value hashtag count 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터 hashtag String 조회한 해시태그 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 입력 오류 hashtag, count 값을 확인하세요. 404 결과 없음 해시태그 페이지를 찾을 수 없습니다. 408 시간 초과 처리 시간이 초과됐습니다. 과금하지 않습니다. 424 조회 불가 일시적으로 가져오지 못했습니다. 잠시 후 다시 시도해 주세요. 실패한 호출은 과금하지 않습니다. ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "hashtag": "kpop", "count": 1, "videos": [ { "type": "video", "id": "yebNIHKAC4A", "url": "https://www.youtube.com/watch?v=yebNIHKAC4A", "title": "“Golden” Official Lyric Video | KPop Demon Hunters", "description": null, "duration": 199, "view_count": 1761885143, "live_status": null, "published_at": null, "channel": { "id": "UCnLuLSV-Oi0ctqjxGgxFlmg", "name": "Sony Pictures Animation", "url": "https://www.youtube.com/channel/UCnLuLSV-Oi0ctqjxGgxFlmg", "handle": null }, "thumbnail": "https://i.ytimg.com/vi/yebNIHKAC4A/hqdefault.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595635, "ms": 3210 } }