# 유튜브 다운로드 화질 조회



유튜브 공개 영상에서 받을 수 있는 화질·코덱·용량과 오디오 형식, 화질별 예상 다운로드 요금을 조회합니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/youtube_formats 응답 필드

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

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

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

- `data.duration` (integer): 영상 길이(초)

- `data.live_status` (string): 라이브 상태(not_live·is_live·was_live 등)

- `data.downloadable` (boolean): 다운로드 가능 여부. 진행 중·예정 라이브는 false

- `data.video_formats` (array): 영상 형식 목록 (높은 화질 순)

- `data.video_formats[].quality` (string): 화질 이름 (예: 1080p)

- `data.video_formats[].width` (integer): 가로 픽셀

- `data.video_formats[].height` (integer): 세로 픽셀

- `data.video_formats[].fps` (integer): 초당 프레임 수

- `data.video_formats[].codec` (string): 영상 코덱 (H.264·VP9·AV1 등)

- `data.video_formats[].hdr` (boolean): HDR 여부

- `data.video_formats[].has_audio` (boolean): 소리가 함께 들어 있는 형식인지 여부

- `data.video_formats[].bitrate_kbps` (integer): 평균 비트레이트(kbps)

- `data.video_formats[].filesize` (integer): 용량(바이트). 모르면 null null 허용.

- `data.video_formats[].filesize_estimated` (boolean): 용량이 추정값인지 여부

- `data.audio_formats` (array): 오디오 형식 목록 (높은 비트레이트 순)

- `data.audio_formats[].codec` (string): 오디오 코덱 (AAC·Opus 등)

- `data.audio_formats[].bitrate_kbps` (integer): 비트레이트(kbps)

- `data.audio_formats[].sample_rate` (integer): 샘플레이트(Hz)

- `data.audio_formats[].channels` (integer): 채널 수

- `data.audio_formats[].language` (string): 음성 언어 코드. 모르면 null null 허용.

- `data.audio_formats[].filesize` (integer): 용량(바이트)

- `data.audio_formats[].filesize_estimated` (boolean): 용량이 추정값인지 여부

- `data.download_options` (object): 다운로드 API로 받을 때의 예상 용량·요금(선불 기준)

- `data.download_options.video` (array): 화질별 {quality, estimated_size, estimated_cost}. quality 값을 그대로 유튜브 동영상 다운로드의 quality 로 쓸 수 있습니다.

- `data.download_options.video[].quality` (string): 아래 하위 항목을 확인하세요.

- `data.download_options.video[].estimated_size` (integer): 아래 하위 항목을 확인하세요.

- `data.download_options.video[].estimated_cost` (integer): 아래 하위 항목을 확인하세요.

- `data.download_options.audio` (array): 오디오 {format, bitrate, estimated_size, estimated_cost}

- `data.download_options.audio[].format` (string): 아래 하위 항목을 확인하세요.

- `data.download_options.audio[].bitrate` (integer): 아래 하위 항목을 확인하세요. null 허용.

- `data.download_options.audio[].estimated_size` (integer): 아래 하위 항목을 확인하세요.

- `data.download_options.audio[].estimated_cost` (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_formats



### 입력

- `url` (string, 필수): 유튜브 영상 URL 또는 11자리 영상 ID



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "video_id": {
          "type": "string",
          "description": "11자리 영상 ID"
        },
        "title": {
          "type": "string",
          "description": "영상 제목"
        },
        "duration": {
          "type": "integer",
          "description": "영상 길이(초)"
        },
        "live_status": {
          "type": "string",
          "description": "라이브 상태(not_live·is_live·was_live 등)"
        },
        "downloadable": {
          "type": "boolean",
          "description": "다운로드 가능 여부. 진행 중·예정 라이브는 false"
        },
        "video_formats": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "quality": {
                "type": "string",
                "description": "화질 이름 (예: 1080p)"
              },
              "width": {
                "type": "integer",
                "description": "가로 픽셀"
              },
              "height": {
                "type": "integer",
                "description": "세로 픽셀"
              },
              "fps": {
                "type": "integer",
                "description": "초당 프레임 수"
              },
              "codec": {
                "type": "string",
                "description": "영상 코덱 (H.264·VP9·AV1 등)"
              },
              "hdr": {
                "type": "boolean",
                "description": "HDR 여부"
              },
              "has_audio": {
                "type": "boolean",
                "description": "소리가 함께 들어 있는 형식인지 여부"
              },
              "bitrate_kbps": {
                "type": "integer",
                "description": "평균 비트레이트(kbps)"
              },
              "filesize": {
                "type": "integer",
                "description": "용량(바이트). 모르면 null",
                "nullable": true
              },
              "filesize_estimated": {
                "type": "boolean",
                "description": "용량이 추정값인지 여부"
              }
            }
          },
          "description": "영상 형식 목록 (높은 화질 순)"
        },
        "audio_formats": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "codec": {
                "type": "string",
                "description": "오디오 코덱 (AAC·Opus 등)"
              },
              "bitrate_kbps": {
                "type": "integer",
                "description": "비트레이트(kbps)"
              },
              "sample_rate": {
                "type": "integer",
                "description": "샘플레이트(Hz)"
              },
              "channels": {
                "type": "integer",
                "description": "채널 수"
              },
              "language": {
                "type": "string",
                "description": "음성 언어 코드. 모르면 null",
                "nullable": true
              },
              "filesize": {
                "type": "integer",
                "description": "용량(바이트)"
              },
              "filesize_estimated": {
                "type": "boolean",
                "description": "용량이 추정값인지 여부"
              }
            }
          },
          "description": "오디오 형식 목록 (높은 비트레이트 순)"
        },
        "download_options": {
          "type": "object",
          "properties": {
            "video": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "quality": {
                    "type": "string"
                  },
                  "estimated_size": {
                    "type": "integer"
                  },
                  "estimated_cost": {
                    "type": "integer"
                  }
                }
              },
              "description": "화질별 {quality, estimated_size, estimated_cost}. quality 값을 그대로 유튜브 동영상 다운로드의 quality 로 쓸 수 있습니다."
            },
            "audio": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "format": {
                    "type": "string"
                  },
                  "bitrate": {
                    "type": "integer",
                    "nullable": true
                  },
                  "estimated_size": {
                    "type": "integer"
                  },
                  "estimated_cost": {
                    "type": "integer"
                  }
                }
              },
              "description": "오디오 {format, bitrate, estimated_size, estimated_cost}"
            }
          },
          "description": "다운로드 API로 받을 때의 예상 용량·요금(선불 기준)"
        },
        "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": "9bZkp7q19f0",
    "title": "PSY - GANGNAM STYLE(강남스타일) M/V",
    "duration": 252,
    "live_status": "not_live",
    "downloadable": true,
    "video_formats": [
      {
        "quality": "1080p",
        "width": 1920,
        "height": 1080,
        "fps": 24,
        "codec": "H.264",
        "hdr": false,
        "has_audio": false,
        "bitrate_kbps": 3418,
        "filesize": 107750453,
        "filesize_estimated": false
      },
      {
        "quality": "720p",
        "width": 1280,
        "height": 720,
        "fps": 24,
        "codec": "VP9",
        "hdr": false,
        "has_audio": false,
        "bitrate_kbps": 1073,
        "filesize": 33812907,
        "filesize_estimated": false
      }
    ],
    "audio_formats": [
      {
        "codec": "AAC",
        "bitrate_kbps": 130,
        "sample_rate": 44100,
        "channels": 2,
        "language": "ko",
        "filesize": 4083640,
        "filesize_estimated": false
      }
    ],
    "download_options": {
      "video": [
        {
          "quality": "1080",
          "estimated_size": 111834093,
          "estimated_cost": 52
        },
        {
          "quality": "720",
          "estimated_size": 44693079,
          "estimated_cost": 40
        }
      ],
      "audio": [
        {
          "format": "mp3",
          "bitrate": 192,
          "estimated_size": 6048000,
          "estimated_cost": 22
        },
        {
          "format": "m4a",
          "bitrate": null,
          "estimated_size": 4083640,
          "estimated_cost": 22
        }
      ]
    },
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 10,
    "pl_id": 1595635,
    "ms": 3210
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_formats' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://youtu.be/9bZkp7q19f0'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("url", "https://youtu.be/9bZkp7q19f0");
const response = await fetch("https://apick.app/rest/youtube_formats", {
  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://youtu.be/9bZkp7q19f0")),
]
response = requests.request("POST", "https://apick.app/rest/youtube_formats",
    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://youtu.be/9bZkp7q19f0',
];
$curl = curl_init('https://apick.app/rest/youtube_formats');
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_formats API 호출 요청 요청하기 Key Value url 응답

## 상세 요청

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

## 상세 응답

Body 이름 타입 설명 data Object 조회 데이터 video_id String 11자리 영상 ID title String 영상 제목 duration Integer 영상 길이(초) live_status String 라이브 상태(not_live·is_live·was_live 등) downloadable Boolean 다운로드 가능 여부. 진행 중·예정 라이브는 false video_formats Array 영상 형식 목록 (높은 화질 순) quality String 화질 이름 (예: 1080p) width Integer 가로 픽셀 height Integer 세로 픽셀 fps Integer 초당 프레임 수 codec String 영상 코덱 (H.264·VP9·AV1 등) hdr Boolean HDR 여부 has_audio Boolean 소리가 함께 들어 있는 형식인지 여부 bitrate_kbps Integer 평균 비트레이트(kbps) filesize Integer 용량(바이트). 모르면 null filesize_estimated Boolean 용량이 추정값인지 여부 audio_formats Array 오디오 형식 목록 (높은 비트레이트 순) codec String 오디오 코덱 (AAC·Opus 등) bitrate_kbps Integer 비트레이트(kbps) sample_rate Integer 샘플레이트(Hz) channels Integer 채널 수 language String 음성 언어 코드. 모르면 null filesize Integer 용량(바이트) filesize_estimated Boolean 용량이 추정값인지 여부 download_options Object 다운로드 API로 받을 때의 예상 용량·요금(선불 기준) video Array 화질별 {quality, estimated_size, estimated_cost}. quality 값을 그대로 유튜브 동영상 다운로드의 quality 로 쓸 수 있습니다. audio Array 오디오 {format, bitrate, estimated_size, estimated_cost} 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 영상 없음 삭제·비공개 영상이거나 잘못된 주소입니다. 408 시간 초과 처리 시간이 초과됐습니다. 과금하지 않습니다. 424 조회 불가 연령 제한·회원 전용 영상이거나 일시적으로 조회하지 못했습니다. 실패한 호출은 과금하지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "video_id": "9bZkp7q19f0", "title": "PSY - GANGNAM STYLE(강남스타일) M/V", "duration": 252, "live_status": "not_live", "downloadable": true, "video_formats": [ { "quality": "1080p", "width": 1920, "height": 1080, "fps": 24, "codec": "H.264", "hdr": false, "has_audio": false, "bitrate_kbps": 3418, "filesize": 107750453, "filesize_estimated": false }, { "quality": "720p", "width": 1280, "height": 720, "fps": 24, "codec": "VP9", "hdr": false, "has_audio": false, "bitrate_kbps": 1073, "filesize": 33812907, "filesize_estimated": false } ], "audio_formats": [ { "codec": "AAC", "bitrate_kbps": 130, "sample_rate": 44100, "channels": 2, "language": "ko", "filesize": 4083640, "filesize_estimated": false } ], "download_options": { "video": [ { "quality": "1080", "estimated_size": 111834093, "estimated_cost": 52 }, { "quality": "720", "estimated_size": 44693079, "estimated_cost": 40 } ], "audio": [ { "format": "mp3", "bitrate": 192, "estimated_size": 6048000, "estimated_cost": 22 }, { "format": "m4a", "bitrate": null, "estimated_size": 4083640, "estimated_cost": 22 } ] }, "success": 1 }, "api": { "success": true, "cost": 10, "pl_id": 1595635, "ms": 3210 } }