# 유튜브 해시태그 영상 조회



해시태그 하나에 올라온 유튜브 영상·쇼츠 목록을 받습니다. 트렌드 모니터링이나 주제별 콘텐츠 목록을 만들 때 씁니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/youtube_hashtag 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.hashtag` (string): #을 뺀 해시태그입니다. 저장·비교할 때 이 값을 쓰세요. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.count` (integer): 이번 응답에 담긴 영상 수입니다. 요청한 수보다 적으면 그 해시태그에 올라온 영상이 그만큼만 있는 것입니다.

- `data.videos` (array): 조회한 영상 목록입니다. 영상이 없으면 빈 배열이며, 각 항목에 제목·주소·조회 수·채널 정보가 들어 있습니다.

- `data.videos[].type` (string): YouTube 항목 종류입니다. video·channel·playlist 등이 오며, 같은 목록에 여러 종류가 섞일 수 있습니다. 가능한 값은 3가지입니다. video = 동영상만 결과에 포함하는 값입니다. 채널·재생목록은 제외됩니다. channel = 채널만 결과에 포함하는 값입니다. 채널명·핸들로 검색할 때 사용합니다. playlist = 재생목록만 결과에 포함하는 값입니다.

- `data.videos[].id` (string): YouTube 항목의 고유 ID입니다. 영상은 11자리, 채널은 UC로 시작하는 ID가 옵니다.

- `data.videos[].url` (string): YouTube에서 항목을 열 수 있는 주소입니다. http·https로 시작하는 전체 URL입니다. 대상 페이지를 앱에서 바로 열 수 있으며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.videos[].title` (string): 영상·채널·재생목록의 제목입니다. 대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다. null 허용.

- `data.videos[].description` (string): 항목 설명문입니다. 설명이 없으면 빈 문자열이거나 필드가 생략됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.videos[].duration` (integer): 영상 길이(초)입니다. 라이브·미리보기처럼 길이를 알 수 없는 항목은 0이거나 생략됩니다. null 허용.

- `data.videos[].view_count` (integer): 누적 조회 수입니다. 집계 시점에 따라 실제 화면 숫자와 조금 다를 수 있습니다. null 허용.

- `data.videos[].live_status` (string): 라이브 상태입니다. 일반 영상·종료된 라이브·진행 중 라이브를 구분합니다. 가능한 값은 4가지입니다. is_live = 지금 라이브 방송이 진행 중인 경우, was_live = 과거 라이브가 끝나 다시보기로 남은 경우, is_upcoming = 라이브가 예정되어 아직 시작하지 않은 경우, not_live = 라이브가 아닌 일반 업로드 영상인 경우입니다. null이면 상태를 확인하지 못한 것입니다. null 허용.

- `data.videos[].published_at` (string): 게시 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.videos[].channel` (object): 영상이 올라온 채널 정보 묶음입니다. 채널 ID·이름·주소·핸들을 함께 제공합니다. null 허용.

- `data.videos[].channel.id` (string): 채널 고유 ID입니다. UC로 시작하며, 채널을 식별하는 가장 정확한 값입니다.

- `data.videos[].channel.name` (string): 채널 표시 이름입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.videos[].channel.url` (string): 채널 페이지 주소입니다. http·https로 시작하는 전체 URL입니다. 대상 페이지를 앱에서 바로 열 수 있으며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.videos[].channel.handle` (string): 채널 핸들(@이름)입니다. 핸들을 설정하지 않은 채널은 null이거나 생략됩니다.

- `data.videos[].thumbnail` (string): 대표 썸네일 이미지 주소입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## 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",
                "description": "video(영상) 또는 short(쇼츠)입니다."
              },
              "id": {
                "type": "string",
                "description": "영상 ID(11자리)입니다."
              },
              "url": {
                "type": "string",
                "description": "영상 주소입니다. 쇼츠는 /shorts/ 주소입니다."
              },
              "title": {
                "type": "string",
                "description": "제목입니다. 없으면 null입니다.",
                "nullable": true
              },
              "description": {
                "nullable": true,
                "type": "string",
                "description": "설명 일부입니다. 없으면 null입니다."
              },
              "duration": {
                "type": "integer",
                "description": "영상 길이(초)입니다. 모르면 null입니다.",
                "nullable": true
              },
              "view_count": {
                "type": "integer",
                "description": "조회수입니다. 제공되지 않으면 null입니다.",
                "nullable": true
              },
              "live_status": {
                "nullable": true,
                "type": "string",
                "description": "라이브 상태입니다. 일반 영상은 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}입니다. 없으면 null입니다.",
                "nullable": true
              },
              "thumbnail": {
                "type": "string",
                "description": "대표 썸네일 주소입니다. 없으면 null입니다.",
                "nullable": true
              }
            }
          },
          "description": "영상·쇼츠 목록입니다. 둘이 섞여 오므로 type(video·short)으로 구분합니다."
        },
        "success": {
          "type": "integer",
          "description": "성공이면 1입니다."
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer",
          "description": "차감된 포인트입니다. 실패하면 0입니다."
        },
        "ms": {
          "type": "integer",
          "description": "처리 시간(밀리초)입니다."
        },
        "pl_id": {
          "type": "integer",
          "description": "결제 기록 번호입니다. 성공한 응답에만 옵니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "hashtag": "kpop",
    "count": 1,
    "videos": [
      {
        "type": "short",
        "id": "aBcDeFgHiJk",
        "url": "https://www.youtube.com/shorts/aBcDeFgHiJk",
        "title": "예시 쇼츠",
        "description": null,
        "duration": 28,
        "view_count": 540000,
        "live_status": null,
        "published_at": null,
        "channel": {
          "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
          "name": "예시 채널",
          "url": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
          "handle": "@example"
        },
        "thumbnail": "https://i.ytimg.com/vi/aBcDeFgHiJk/hqdefault.jpg"
      }
    ],
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 20,
    "ms": 4200,
    "pl_id": 1595635
  }
}

```

### 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=30'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("hashtag", "kpop");
form.append("count", "30");
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, "30")),
]
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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'hashtag' => 'kpop',
    'count' => '30',
];
$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);

```

## 사용 예시 1. 해시태그 영상 30개

# 없이 해시태그만 보냅니다. count를 생략하면 30개입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_hashtag' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'hashtag=kpop'

```

- `data.videos[]`에 영상과 쇼츠가 섞여 올 수 있습니다. `type`으로 구분하세요.

- `data.count`가 요청한 수보다 적으면 해시태그에 올라온 영상이 그만큼만 있는 것입니다.

## 사용 예시 2. 한글 해시태그를 #과 함께

사용자가 입력한 #을 지우지 않고 보내도 됩니다. 한글·숫자·밑줄을 쓸 수 있고 공백·기호는 쓸 수 없습니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_hashtag' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'hashtag=#여행브이로그' \
  --form-string 'count=50'

```

- `data.hashtag`에는 #을 뺀 해시태그가 돌아옵니다.

- 공백이 들어가면 입력 오류(HTTP 400)입니다. 띄어쓰기를 지우고 보내세요.

## 사용 예시 3. 최대 100개 받기

해시태그 영상을 한 번에 많이 받을 때의 상한은 100개입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_hashtag' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'hashtag=shorts' \
  --form-string 'count=100'

```

- `data.videos[].view_count`와 `published_at`은 제공되지 않으면 null입니다. 필요하면 영상 정보 조회 API로 보완하세요.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

이용 전 확인 성공한 조회 한 건당 20P가 차감됩니다. 실제 차감액은 응답의 api.cost에서 확인하세요. 입력 오류·해시태그 없음·시간 초과처럼 실패한 호출은 data.error로 안내 문구가 오고 과금되지 않습니다(api.cost 0). 목록이 비어 data.count가 0인 응답이 정상 응답으로 오면 과금됩니다. 한 번에 최대 100개까지 받습니다. 항목 형식은 유튜브 검색 결과의 영상·쇼츠 항목과 같습니다. 정확한 업로드일·좋아요 수가 필요하면 각 id로 영상 정보 조회를 이어서 요청하세요. 응답 시간은 보통 6초 이내이고 최대 약 60초입니다. 요청 시간 제한을 90초 이상으로 잡으세요. 인증키는 서버 환경변수에 보관하고 공개 저장소·웹페이지에 넣지 마세요. API 호출 요청 요청하기 Key Value hashtag count 응답

## 상세 요청

항목설정 메서드·주소POST https://apick.app/rest/youtube_hashtag 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data 요청 예시 해시태그 영상 30개를 받는 예입니다. 성공 시 과금되는 실제 요청입니다. form-data 전체 예제 보기

## 상세 응답

필드타입설명 data.hashtagstring#을 뺀 해시태그입니다. 저장·비교할 때 이 값을 쓰세요. data.countinteger이번 응답에 담긴 영상 수입니다. 요청한 수보다 적으면 그 해시태그에 올라온 영상이 그만큼만 있는 것입니다. data.videos[]array영상·쇼츠 목록입니다. 둘이 섞여 오므로 type(video·short)으로 구분합니다. data.videos[].typestringvideo(영상) 또는 short(쇼츠)입니다. data.videos[].idstring영상 ID(11자리)입니다. data.videos[].urlstring영상 주소입니다. 쇼츠는 /shorts/ 주소입니다. data.videos[].titlestring제목입니다. 없으면 null입니다. data.videos[].descriptionstring설명 일부입니다. 없으면 null입니다. data.videos[].durationinteger영상 길이(초)입니다. 모르면 null입니다. data.videos[].view_countinteger조회수입니다. 제공되지 않으면 null입니다. data.videos[].live_statusstring라이브 상태입니다. 일반 영상은 null입니다. data.videos[].published_atstring게시 시각(ISO 8601)입니다. 제공되지 않으면 null입니다. data.videos[].channelobject올린 채널 {id, name, url, handle}입니다. 없으면 null입니다. data.videos[].thumbnailstring대표 썸네일 주소입니다. 없으면 null입니다. data.successinteger성공이면 1입니다. api.costinteger차감된 포인트입니다. 실패하면 0입니다. api.msinteger처리 시간(밀리초)입니다. api.pl_idinteger결제 기록 번호입니다. 성공한 응답에만 옵니다. { "data": { "hashtag": "kpop", "count": 1, "videos": [ { "type": "short", "id": "aBcDeFgHiJk", "url": "https://www.youtube.com/shorts/aBcDeFgHiJk", "title": "예시 쇼츠", "description": null, "duration": 28, "view_count": 540000, "live_status": null, "published_at": null, "channel": { "id": "UCxxxxxxxxxxxxxxxxxxxxxx", "name": "예시 채널", "url": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx", "handle": "@example" }, "thumbnail": "https://i.ytimg.com/vi/aBcDeFgHiJk/hqdefault.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "ms": 4200, "pl_id": 1595635 } } 예시는 길이를 줄이려고 항목 한 개만 적었습니다. ID·채널·수치는 설명을 위한 값입니다.

## 상세 코드·정책

오류와 복구 아래 경우는 data.error로 응답하며 과금되지 않습니다(api.cost 0). 실패 응답은 표의 HTTP 상태 코드와 함께 옵니다. 화면에 보여 줄 안내는 본문의 data.error를 쓰세요. 상황HTTPdata.error해결 입력 오류400입력 항목이 잘못됐습니다. hashtag(문자·숫자·밑줄 1~100자)와 count(1~100)를 확인해 주세요.띄어쓰기·기호를 지우고, count를 1~100 정수로 보냅니다. 해시태그 없음404해시태그 영상을 찾을 수 없습니다.철자를 확인하거나 다른 해시태그로 요청합니다. 시간 초과408처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다. count를 줄이면 빨라집니다. 일시적 조회 실패424일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다.

## 상세 예제

호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기
