# 유튜브 검색



검색어로 유튜브 영상·쇼츠·채널·재생목록을 찾습니다. 결과 종류·업로드 시기·영상 길이로 거르고 정렬을 바꿀 수 있으며, 결과의 id는 영상 정보·댓글·자막·채널·재생목록 조회에 그대로 넣을 수 있습니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/youtube_search 응답 필드

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

- `data.query` (string): 검색에 사용한 키워드를 그대로 반환한 값입니다. 응답의 결과가 어떤 검색어 기준인지 확인할 때 사용합니다.

- `data.count` (integer): 이번 응답에 담긴 결과 수입니다. 0이면 조건에 맞는 결과가 없습니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.results` (array): 조회 결과 항목 목록입니다. 항목이 없으면 빈 배열입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.

- `data.results[].type` (string): video(영상)·short(쇼츠)·channel(채널)·playlist(재생목록) 중 하나입니다. 가능한 값은 4가지입니다. video = 일반 동영상 항목, short = 짧은 영상(쇼츠) 항목, channel = 채널 항목, playlist = 재생목록 항목입니다. 목록에 여러 종류가 섞여 오므로 항목별로 이 값을 확인하세요.

- `data.results[].id` (string): 영상 ID(11자리)·채널 ID(UC…)·재생목록 ID입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

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

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

- `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입니다. 가능한 값은 4가지입니다. is_live = 지금 라이브 방송이 진행 중인 경우, was_live = 과거 라이브가 끝나 다시보기로 남은 경우, is_upcoming = 라이브가 예정되어 아직 시작하지 않은 경우, not_live = 라이브가 아닌 일반 업로드 영상인 경우입니다. null이면 상태를 확인하지 못한 것입니다. null 허용.

- `data.results[].published_at` (string): 게시 시각(ISO 8601)입니다. 영상·쇼츠 항목만이며 제공되지 않으면 null입니다. null 허용.

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

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

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

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

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

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

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

- `data.results[].follower_count` (integer): 구독자 수입니다. 채널 항목만이며 비공개면 null입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. null 허용.

- `data.results[].is_verified` (boolean): 인증 채널 여부입니다. 채널 항목만입니다. 검증 완료 여부입니다. true면 서비스가 공식 인증한 계정·채널이고, false면 인증 표시가 없습니다.

- `data.results[].video_count` (integer): 수록 영상 수입니다. 재생목록 항목만이며 모르면 null입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. 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_search



### 입력

- `query` (string, 필수): 검색할 키워드입니다. 1~200자까지 보낼 수 있으며, 여러 단어는 공백으로 구분합니다. 특수문자는 검색 결과에 영향을 줄 수 있습니다.

- `count` (integer, 선택): 결과 수 1~50 (기본 10) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

- `sort` (string, 선택): 정렬: relevance(관련도, 기본)·date(업로드일)·views(조회수)·rating(평점) 가능한 값은 4가지입니다. relevance = 검색어와의 관련도가 높은 순서로 정렬하는 값입니다. 기본 정렬로 가장 많이 쓰입니다. date = 날짜(최신순) 기준으로 정렬하는 값입니다. 최신 항목을 먼저 확인할 때 사용합니다. views = 조회수(인기) 순으로 정렬하는 값입니다. rating = 평점이 높은 순서로 정렬하는 값입니다. 허용값: relevance, date, views, rating

- `type` (string, 선택): 결과 종류 (기본 any) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 5가지입니다. any = 종류·기간을 제한하지 않는 값입니다. 가장 넓은 결과가 오므로 관련도가 낮은 항목도 포함됩니다. video = 동영상만 결과에 포함하는 값입니다. 채널·재생목록은 제외됩니다. channel = 채널만 결과에 포함하는 값입니다. 채널명·핸들로 검색할 때 사용합니다. playlist = 재생목록만 결과에 포함하는 값입니다. movie = 영화(정식 작품)만 결과에 포함하는 값입니다. 허용값: any, video, channel, playlist, movie

- `upload_date` (string, 선택): 업로드 시기 (기본 any) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 6가지입니다. any = 종류·기간을 제한하지 않는 값입니다. 가장 넓은 결과가 오므로 관련도가 낮은 항목도 포함됩니다. hour = 최근 1시간 안에 올라온 결과만 포함하는 값입니다. today = 오늘 올라온 결과만 포함하는 값입니다. week = 최근 1주일 안의 결과만 포함하는 값입니다. month = 최근 1개월 안의 결과만 포함하는 값입니다. year = 최근 1년 안의 결과만 포함하는 값입니다. 허용값: any, hour, today, week, month, year

- `duration` (string, 선택): 길이: short(4분 미만)·medium(4~20분)·long(20분 초과) 가능한 값은 4가지입니다. any = 종류·기간을 제한하지 않는 값입니다. 가장 넓은 결과가 오므로 관련도가 낮은 항목도 포함됩니다. 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": "이번 응답에 담긴 결과 수입니다. 0이면 조건에 맞는 결과가 없습니다."
        },
        "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": "항목 주소입니다. 쇼츠는 /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": "라이브 상태(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"
                  }
                },
                "nullable": true,
                "description": "올린 채널 {id, name, url, handle}입니다. 영상·쇼츠·재생목록 항목에 오며 없으면 null입니다."
              },
              "thumbnail": {
                "type": "string",
                "description": "대표 썸네일 주소입니다. 없으면 null입니다.",
                "nullable": true
              },
              "handle": {
                "type": "string",
                "description": "채널 핸들(@이름)입니다. 채널 항목만이며 없으면 null입니다.",
                "nullable": true
              },
              "follower_count": {
                "type": "integer",
                "description": "구독자 수입니다. 채널 항목만이며 비공개면 null입니다.",
                "nullable": true
              },
              "is_verified": {
                "type": "boolean",
                "description": "인증 채널 여부입니다. 채널 항목만입니다."
              },
              "video_count": {
                "type": "integer",
                "description": "수록 영상 수입니다. 재생목록 항목만이며 모르면 null입니다.",
                "nullable": true
              }
            }
          },
          "description": "검색 결과 목록입니다. 항목마다 type에 따라 채워지는 필드가 다릅니다."
        },
        "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": {
    "query": "파이썬 기초 강좌",
    "count": 2,
    "results": [
      {
        "type": "video",
        "id": "Xy12AbCdEfG",
        "url": "https://www.youtube.com/watch?v=Xy12AbCdEfG",
        "title": "파이썬 기초 강좌 1강",
        "description": null,
        "duration": 1532,
        "view_count": 1200000,
        "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/Xy12AbCdEfG/hqdefault.jpg"
      },
      {
        "type": "short",
        "id": "aBcDeFgHiJk",
        "url": "https://www.youtube.com/shorts/aBcDeFgHiJk",
        "title": "파이썬 1분 팁",
        "description": null,
        "duration": 45,
        "view_count": 35000,
        "live_status": null,
        "published_at": null,
        "channel": null,
        "thumbnail": "https://i.ytimg.com/vi/aBcDeFgHiJk/hqdefault.jpg"
      }
    ],
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 20,
    "ms": 4100,
    "pl_id": 1595635
  }
}

```

### 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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'query' => '파이썬 기초 강좌',
    '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);

```

## 사용 예시 1. 키워드로 영상 검색

검색어 하나로 관련도순 상위 결과를 받는 기본 요청입니다. 결과 수를 정하지 않으면 10개입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'type=video' \
  --form-string 'query=파이썬 기초 강좌' \
  --form-string 'count=10'

```

- `data.results[]`의 `type`이 video·short·channel·playlist 중 무엇인지 먼저 보고 항목별 필드를 읽습니다.

- `data.count`가 0이면 검색 결과가 없는 것입니다. 검색어를 바꿔 다시 요청하세요.

## 사용 예시 2. 이번 주 올라온 영상을 조회수순으로

최근 반응이 큰 영상을 찾을 때 업로드 시기와 정렬을 함께 지정합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'query=캠핑 요리' \
  --form-string 'type=video' \
  --form-string 'upload_date=week' \
  --form-string 'sort=views' \
  --form-string 'count=20'

```

- `data.results[].view_count`가 큰 순서로 옵니다. 값이 null인 항목은 조회수가 제공되지 않은 것입니다.

- `published_at`은 제공되지 않으면 null입니다. 정확한 업로드일이 필요하면 영상 정보 조회 API로 `upload_date`를 확인하세요.

## 사용 예시 3. 채널만 찾기

주제와 관련된 채널 목록을 만들 때 결과 종류를 channel로 제한합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'query=홈베이킹' \
  --form-string 'type=channel' \
  --form-string 'count=5'

```

- 채널 항목은 `data.results[].follower_count`(구독자 수)와 `handle`, `is_verified`를 함께 줍니다.

- `id`(UC…)를 유튜브 채널 조회 API의 `channel`에 넣으면 채널의 영상 목록을 이어서 받을 수 있습니다.

## 사용 예시 4. 20분이 넘는 긴 강의만

길이 조건으로 짧은 영상을 걸러 낼 때 사용합니다. short는 4분 미만, medium은 4~20분, long은 20분 초과입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'query=엑셀 함수 강의' \
  --form-string 'type=video' \
  --form-string 'duration=long'

```

- `data.results[].duration`은 초 단위입니다. 화면에는 시:분:초로 바꿔 표시하세요.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 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인 응답도 정상 응답이라 과금됩니다. 한 번에 최대 50개까지 받습니다. 다음 페이지를 넘기는 기능은 없으므로 더 많은 결과가 필요하면 검색어나 조건을 나눠 요청하세요. 응답 시간은 보통 6초 이내이고 최대 약 60초입니다. 요청 시간 제한을 90초 이상으로 잡으세요. 인증키는 서버 환경변수에 보관하고 공개 저장소·웹페이지에 넣지 마세요. API 호출 요청 요청하기 Key Value query count sort type upload_date duration 응답

## 상세 요청

항목설정 메서드·주소POST https://apick.app/rest/youtube_search 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data sort 허용값 값의미 relevance관련도순 (기본값) date업로드일순(최신 먼저) views조회수순 rating평점순 type 허용값 값의미 any모든 종류 (기본값) video영상·쇼츠만 channel채널만 playlist재생목록만 movie영화만 upload_date 허용값 값의미 any제한 없음 (기본값) hour지난 1시간 today오늘 week이번 주 month이번 달 year올해 duration 허용값 값의미 any제한 없음 (기본값) short4분 미만 medium4~20분 long20분 초과 요청 예시 영상만 2개 받는 예입니다. 성공 시 과금되는 실제 요청입니다. form-data 전체 예제 보기 조건은 함께 쓸 수 있습니다. 예를 들어 upload_date=week와 sort=views를 함께 보내면 이번 주 올라온 영상을 조회수순으로 받습니다.

## 상세 응답

필드타입설명 data.querystring앞뒤 공백을 지운 검색어입니다. data.countinteger이번 응답에 담긴 결과 수입니다. 0이면 조건에 맞는 결과가 없습니다. data.results[]array검색 결과 목록입니다. 항목마다 type에 따라 채워지는 필드가 다릅니다. data.results[].typestringvideo(영상)·short(쇼츠)·channel(채널)·playlist(재생목록) 중 하나입니다. data.results[].idstring영상 ID(11자리)·채널 ID(UC…)·재생목록 ID입니다. data.results[].urlstring항목 주소입니다. 쇼츠는 /shorts/ 주소입니다. data.results[].titlestring제목입니다. 채널은 채널 이름입니다. 없으면 null입니다. data.results[].descriptionstring설명 일부입니다. 영상·쇼츠·채널 항목에 오며 없으면 null입니다. data.results[].durationinteger영상 길이(초)입니다. 영상·쇼츠 항목만이며 모르면 null입니다. data.results[].view_countinteger조회수입니다. 영상·쇼츠 항목만이며 모르면 null입니다. data.results[].live_statusstring라이브 상태(is_live·was_live 등)입니다. 영상·쇼츠 항목만이며 일반 영상은 null입니다. data.results[].published_atstring게시 시각(ISO 8601)입니다. 영상·쇼츠 항목만이며 제공되지 않으면 null입니다. data.results[].channelobject올린 채널 {id, name, url, handle}입니다. 영상·쇼츠·재생목록 항목에 오며 없으면 null입니다. data.results[].handlestring채널 핸들(@이름)입니다. 채널 항목만이며 없으면 null입니다. data.results[].follower_countinteger구독자 수입니다. 채널 항목만이며 비공개면 null입니다. data.results[].is_verifiedboolean인증 채널 여부입니다. 채널 항목만입니다. data.results[].video_countinteger수록 영상 수입니다. 재생목록 항목만이며 모르면 null입니다. data.results[].thumbnailstring대표 썸네일 주소입니다. 없으면 null입니다. data.successinteger성공이면 1입니다. api.costinteger차감된 포인트입니다. 실패하면 0입니다. api.msinteger처리 시간(밀리초)입니다. api.pl_idinteger결제 기록 번호입니다. 성공한 응답에만 옵니다. 항목의 type을 먼저 보고 필드를 읽으세요. 영상·쇼츠는 duration·view_count·channel, 채널은 handle·follower_count·is_verified, 재생목록은 video_count·channel입니다. 정확한 업로드일·좋아요 수는 유튜브 영상 정보 조회로 확인하세요. { "data": { "query": "파이썬 기초 강좌", "count": 2, "results": [ { "type": "video", "id": "Xy12AbCdEfG", "url": "https://www.youtube.com/watch?v=Xy12AbCdEfG", "title": "파이썬 기초 강좌 1강", "description": null, "duration": 1532, "view_count": 1200000, "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/Xy12AbCdEfG/hqdefault.jpg" }, { "type": "short", "id": "aBcDeFgHiJk", "url": "https://www.youtube.com/shorts/aBcDeFgHiJk", "title": "파이썬 1분 팁", "description": null, "duration": 45, "view_count": 35000, "live_status": null, "published_at": null, "channel": null, "thumbnail": "https://i.ytimg.com/vi/aBcDeFgHiJk/hqdefault.jpg" } ], "success": 1 }, "api": { "success": true, "cost": 20, "ms": 4100, "pl_id": 1595635 } } 예시의 ID·채널·수치는 설명을 위한 값입니다.

## 상세 코드·정책

오류와 복구 아래 경우는 data.error로 응답하며 과금되지 않습니다(api.cost 0). 실패 응답은 표의 HTTP 상태 코드와 함께 옵니다. 화면에 보여 줄 안내는 본문의 data.error를 쓰세요. 상황HTTPdata.error해결 입력 오류400입력 항목이 잘못됐습니다. query(1~200자), count(1~50), sort·type·upload_date·duration 값을 확인해 주세요.검색어 길이, count 범위(1~50 정수), 각 조건의 허용값을 확인해 다시 보냅니다. 시간 초과408처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다. count를 줄이면 빨라집니다. 일시적 조회 실패424일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다.

## 상세 예제

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