# 유튜브 썸네일 다운로드



유튜브 공개 영상의 가장 큰 썸네일 이미지를 JPG 파일로 내려받습니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/youtube_thumbnail 응답 필드

## API 요청: POST /rest/youtube_thumbnail



### 입력

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



### 응답 명세

```json

{
  "type": "string",
  "format": "binary"
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_thumbnail' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://www.youtube.com/watch?v=dQw4w9WgXcQ' \
  --dump-header response.headers --output result.bin
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

```

### 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_thumbnail", {
  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()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.bin", new Uint8Array(await response.arrayBuffer()));

```

### 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_thumbnail",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.bin", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

```

### 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_thumbnail');
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);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.bin', $body);

```

## 코드·오류

## 상세 기능·요금

Method URL POST https://apick.app/rest/youtube_thumbnail

## 상세 요청

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

## 상세 응답

Header 이름 필수 설명 success O API 서버 정상 응답 여부 cost O API 호출 요금 ms O API 응답 시간 Content-Type O image/jpeg Content-Disposition O 파일명 (영상ID.jpg) Body 이름 타입 설명 JPG 이미지 바이너리 데이터 Binary 영상에서 제공하는 가장 큰 썸네일 (보통 1280×720 또는 1920×1080)

## 상세 코드·정책

오류 HTTP 상태 코드 HTTP 상황 설명 400 입력 오류 유튜브 영상 주소 또는 영상 ID가 아닙니다. 오류는 JSON으로 응답합니다. 404 영상 없음 삭제·비공개 영상이거나 썸네일이 없습니다. 424 조회 불가 일시적으로 가져오지 못했습니다. 실패한 호출은 과금하지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 {JPG 형식의 바이너리 데이터}