# 유튜브 자막 다운로드



유튜브 공개 영상의 자막을 언어별로 VTT·SRT·텍스트 파일로 내려받습니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/youtube_subtitle 응답 필드

## API 요청: POST /rest/youtube_subtitle



### 입력

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

- `lang` (string, 필수): 자막 언어 코드 (예: ko, en, en-US, en-orig). 자막 목록 조회 결과의 lang 값. 자동 번역 자막(translated=true)은 실패할 수 있어 원어 자막을 권장

- `format` (string, 선택): 파일 형식 vtt(기본)·srt·txt. txt는 시간 정보를 뺀 본문만 반환합니다.

- `type` (string, 선택): 자막 종류 any(기본: 수동 자막 우선, 없으면 자동 생성)·manual·auto



### 응답 명세

```json

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

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/youtube_subtitle' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'url=https://www.youtube.com/watch?v=dQw4w9WgXcQ' \
  --form-string 'lang=ko' \
  --form-string 'format=srt' \
  --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");
form.append("lang", "ko");
form.append("format", "srt");
const response = await fetch("https://apick.app/rest/youtube_subtitle", {
  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")),
    ("lang", (None, "ko")),
    ("format", (None, "srt")),
]
response = requests.request("POST", "https://apick.app/rest/youtube_subtitle",
    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',
    'lang' => 'ko',
    'format' => 'srt',
];
$curl = curl_init('https://apick.app/rest/youtube_subtitle');
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_subtitle

## 상세 요청

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

## 상세 응답

Header 이름 필수 설명 success O API 서버 정상 응답 여부 cost O API 호출 요금 ms O API 응답 시간 Content-Type O vtt: text/vttsrt: application/x-subriptxt: text/plain (모두 UTF-8) Content-Disposition O 파일명 (영상ID.언어.형식) Body 이름 타입 설명 자막 파일 데이터 Text 요청한 형식의 UTF-8 자막 파일

## 상세 코드·정책

오류 HTTP 상태 코드 HTTP 상황 설명 400 입력 오류 영상 주소, lang, format, type 값을 확인하세요. 오류는 JSON으로 응답합니다. 404 자막·영상 없음 요청한 언어의 자막이 없거나 삭제·비공개 영상입니다. 424 조회 불가 연령 제한·회원 전용 영상이거나 일시적으로 가져오지 못했습니다. 자동 번역 자막은 이 오류가 잦습니다. 실패한 호출은 과금하지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 1 00:00:01,360 --> 00:00:03,040 안녕하세요, 오늘 영상을 시작하겠습니다. 2 00:00:03,200 --> 00:00:06,880 먼저 준비물부터 살펴보겠습니다.