# 유튜브 영상 정보 조회



유튜브 공개 영상의 제목·채널·길이·조회수·좋아요·업로드일·설명·태그·챕터·썸네일 목록을 조회합니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/youtube_metadata 응답 필드

- `data` (object): 조회 데이터

- `data.video_id` (string): 11자리 영상 ID

- `data.url` (string): 영상 주소

- `data.title` (string): 영상 제목

- `data.description` (string): 영상 설명

- `data.channel` (object): 채널 정보

- `data.channel.id` (string): 채널 ID

- `data.channel.name` (string): 채널 이름

- `data.channel.url` (string): 채널 주소

- `data.channel.handle` (string): 채널 핸들(@아이디). 없으면 null null 허용.

- `data.channel.follower_count` (integer): 구독자 수. 비공개이면 null null 허용.

- `data.channel.is_verified` (boolean): 인증 채널 여부

- `data.upload_date` (string): 업로드일 (YYYY-MM-DD)

- `data.duration` (integer): 영상 길이(초). 라이브 방송은 null일 수 있습니다. null 허용.

- `data.view_count` (integer): 조회수

- `data.like_count` (integer): 좋아요 수. 비공개이면 null null 허용.

- `data.comment_count` (integer): 댓글 수. 확인할 수 없으면 null null 허용.

- `data.categories` (array): 카테고리 목록

- `data.tags` (array): 태그 목록

- `data.language` (string): 영상 언어 코드. 없으면 null null 허용.

- `data.live_status` (string): not_live: 일반 영상is_live: 라이브 중was_live: 종료된 라이브is_upcoming: 예정된 라이브

- `data.availability` (string): 공개 범위 (public, unlisted 등)

- `data.age_limit` (integer): 연령 제한(세). 제한이 없으면 0

- `data.chapters` (array): 챕터 목록. 없으면 빈 배열

- `data.chapters[].title` (string): 챕터 제목

- `data.chapters[].start_time` (number): 시작 시각(초)

- `data.chapters[].end_time` (number): 끝 시각(초)

- `data.thumbnail` (string): 가장 큰 썸네일 이미지 주소

- `data.thumbnails` (array): 크기별 썸네일 목록 (큰 순서)

- `data.thumbnails[].url` (string): 이미지 주소

- `data.thumbnails[].width` (integer): 가로(px)

- `data.thumbnails[].height` (integer): 세로(px)

- `data.subtitle_languages` (array): 수동 자막 언어 코드 목록

- `data.automatic_caption_count` (integer): 자동 생성 자막 언어 수

- `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_metadata



### 입력

- `url` (string, 필수): 유튜브 영상 URL 또는 11자리 영상 ID (예: https://www.youtube.com/watch?v=..., https://youtu.be/..., /shorts/...)



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "video_id": {
          "type": "string",
          "description": "11자리 영상 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
            },
            "follower_count": {
              "type": "integer",
              "description": "구독자 수. 비공개이면 null",
              "nullable": true
            },
            "is_verified": {
              "type": "boolean",
              "description": "인증 채널 여부"
            }
          },
          "description": "채널 정보"
        },
        "upload_date": {
          "type": "string",
          "description": "업로드일 (YYYY-MM-DD)"
        },
        "duration": {
          "type": "integer",
          "description": "영상 길이(초). 라이브 방송은 null일 수 있습니다.",
          "nullable": true
        },
        "view_count": {
          "type": "integer",
          "description": "조회수"
        },
        "like_count": {
          "type": "integer",
          "description": "좋아요 수. 비공개이면 null",
          "nullable": true
        },
        "comment_count": {
          "type": "integer",
          "description": "댓글 수. 확인할 수 없으면 null",
          "nullable": true
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "카테고리 목록"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "태그 목록"
        },
        "language": {
          "type": "string",
          "description": "영상 언어 코드. 없으면 null",
          "nullable": true
        },
        "live_status": {
          "type": "string",
          "description": "not_live: 일반 영상is_live: 라이브 중was_live: 종료된 라이브is_upcoming: 예정된 라이브"
        },
        "availability": {
          "type": "string",
          "description": "공개 범위 (public, unlisted 등)"
        },
        "age_limit": {
          "type": "integer",
          "description": "연령 제한(세). 제한이 없으면 0"
        },
        "chapters": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "챕터 제목"
              },
              "start_time": {
                "type": "number",
                "description": "시작 시각(초)"
              },
              "end_time": {
                "type": "number",
                "description": "끝 시각(초)"
              }
            }
          },
          "description": "챕터 목록. 없으면 빈 배열"
        },
        "thumbnail": {
          "type": "string",
          "description": "가장 큰 썸네일 이미지 주소"
        },
        "thumbnails": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "이미지 주소"
              },
              "width": {
                "type": "integer",
                "description": "가로(px)"
              },
              "height": {
                "type": "integer",
                "description": "세로(px)"
              }
            }
          },
          "description": "크기별 썸네일 목록 (큰 순서)"
        },
        "subtitle_languages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "수동 자막 언어 코드 목록"
        },
        "automatic_caption_count": {
          "type": "integer",
          "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": {
    "video_id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
    "description": "The official video for “Never Gonna Give You Up” by Rick Astley...",
    "channel": {
      "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "name": "Rick Astley",
      "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
      "handle": "@RickAstleyYT",
      "follower_count": 4400000,
      "is_verified": true
    },
    "upload_date": "2009-10-25",
    "duration": 213,
    "view_count": 1821534305,
    "like_count": 18000000,
    "comment_count": 2400000,
    "categories": [
      "Music"
    ],
    "tags": [
      "rick astley",
      "Never Gonna Give You Up"
    ],
    "language": "en",
    "live_status": "not_live",
    "availability": "public",
    "age_limit": 0,
    "chapters": [],
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "width": 1920,
        "height": 1080
      },
      {
        "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
        "width": 480,
        "height": 360
      }
    ],
    "subtitle_languages": [
      "de-DE",
      "en",
      "es-419",
      "ja",
      "pt-BR"
    ],
    "automatic_caption_count": 157,
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 20,
    "pl_id": 1595635,
    "ms": 4210
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_metadata' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://www.youtube.com/watch?v=dQw4w9WgXcQ'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("url", "https://www.youtube.com/watch?v=dQw4w9WgXcQ");
const response = await fetch("https://apick.app/rest/youtube_metadata", {
  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/watch?v=dQw4w9WgXcQ")),
]
response = requests.request("POST", "https://apick.app/rest/youtube_metadata",
    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 = [
    'url' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
];
$curl = curl_init('https://apick.app/rest/youtube_metadata');
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_metadata API 호출 요청 요청하기 Key Value url 응답

## 상세 요청

Header 이름 필수 설명 Authorization O Bearer 인증키

## 상세 응답

Body 이름 타입 설명 data Object 조회 데이터 video_id String 11자리 영상 ID url String 영상 주소 title String 영상 제목 description String 영상 설명 channel Object 채널 정보 id String 채널 ID name String 채널 이름 url String 채널 주소 handle String 채널 핸들(@아이디). 없으면 null follower_count Integer 구독자 수. 비공개이면 null is_verified Boolean 인증 채널 여부 upload_date String 업로드일 (YYYY-MM-DD) duration Integer 영상 길이(초). 라이브 방송은 null일 수 있습니다. view_count Integer 조회수 like_count Integer 좋아요 수. 비공개이면 null comment_count Integer 댓글 수. 확인할 수 없으면 null categories Array 카테고리 목록 tags Array 태그 목록 language String 영상 언어 코드. 없으면 null live_status String not_live: 일반 영상is_live: 라이브 중was_live: 종료된 라이브is_upcoming: 예정된 라이브 availability String 공개 범위 (public, unlisted 등) age_limit Integer 연령 제한(세). 제한이 없으면 0 chapters Array 챕터 목록. 없으면 빈 배열 title String 챕터 제목 start_time Number 시작 시각(초) end_time Number 끝 시각(초) thumbnail String 가장 큰 썸네일 이미지 주소 thumbnails Array 크기별 썸네일 목록 (큰 순서) url String 이미지 주소 width Integer 가로(px) height Integer 세로(px) subtitle_languages Array 수동 자막 언어 코드 목록 automatic_caption_count Integer 자동 생성 자막 언어 수 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가 아닙니다. 404 영상 없음 삭제·비공개 영상이거나 잘못된 주소입니다. 424 조회 불가 연령 제한·회원 전용 영상이거나 일시적으로 조회하지 못했습니다. 실패한 호출은 과금하지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "video_id": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "description": "The official video for “Never Gonna Give You Up” by Rick Astley...", "channel": { "id": "UCuAXFkgsw1L7xaCfnd5JJOw", "name": "Rick Astley", "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw", "handle": "@RickAstleyYT", "follower_count": 4400000, "is_verified": true }, "upload_date": "2009-10-25", "duration": 213, "view_count": 1821534305, "like_count": 18000000, "comment_count": 2400000, "categories": ["Music"], "tags": ["rick astley", "Never Gonna Give You Up"], "language": "en", "live_status": "not_live", "availability": "public", "age_limit": 0, "chapters": [], "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "thumbnails": [ { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "width": 1920, "height": 1080 }, { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 480, "height": 360 } ], "subtitle_languages": ["de-DE", "en", "es-419", "ja", "pt-BR"], "automatic_caption_count": 157, "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595635, "ms": 4210 } }