# 유튜브 자막 목록 조회 유튜브 공개 영상에서 제공하는 수동 자막과 자동 생성 자막의 언어 목록을 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/youtube_subtitle_list 응답 필드 - `data` (object): 조회 데이터 - `data.video_id` (string): 11자리 영상 ID - `data.title` (string): 영상 제목 - `data.original_language` (string): 영상 원어(음성 인식 자막 언어) 코드. 확인할 수 없으면 null null 허용. - `data.subtitle_count` (integer): 수동 자막(채널이 올린 자막) 언어 수 - `data.automatic_caption_count` (integer): 자동 생성 자막 언어 수 (자동 번역 포함) - `data.subtitles` (array): 수동 자막 목록. 없으면 빈 배열 - `data.subtitles[].lang` (string): 언어 코드. 자막 다운로드의 lang 값으로 사용합니다. - `data.subtitles[].name` (string): 언어 이름. 없으면 null null 허용. - `data.subtitles[].auto` (boolean): 자동 생성 여부 (subtitles 는 false) - `data.subtitles[].formats` (array): 원본 제공 형식 목록 - `data.automatic_captions` (array): 자동 생성 자막 목록. 항목 구조는 subtitles 와 같고 auto 는 true 입니다. - `data.automatic_captions[].lang` (string): 아래 하위 항목을 확인하세요. - `data.automatic_captions[].name` (string): 아래 하위 항목을 확인하세요. - `data.automatic_captions[].auto` (boolean): 아래 하위 항목을 확인하세요. - `data.automatic_captions[].formats` (array): 아래 하위 항목을 확인하세요. - `data.automatic_captions[].translated` (boolean): 자동 번역 자막 여부. false 는 영상 원어의 음성 인식 자막입니다.자동 번역 자막은 유튜브 제한으로 내려받지 못할 수 있으니 원어 자막을 권장합니다. - `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_subtitle_list ### 입력 - `url` (string, 필수): 유튜브 영상 URL 또는 11자리 영상 ID ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "video_id": { "type": "string", "description": "11자리 영상 ID" }, "title": { "type": "string", "description": "영상 제목" }, "original_language": { "type": "string", "description": "영상 원어(음성 인식 자막 언어) 코드. 확인할 수 없으면 null", "nullable": true }, "subtitle_count": { "type": "integer", "description": "수동 자막(채널이 올린 자막) 언어 수" }, "automatic_caption_count": { "type": "integer", "description": "자동 생성 자막 언어 수 (자동 번역 포함)" }, "subtitles": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "description": "언어 코드. 자막 다운로드의 lang 값으로 사용합니다." }, "name": { "type": "string", "description": "언어 이름. 없으면 null", "nullable": true }, "auto": { "type": "boolean", "description": "자동 생성 여부 (subtitles 는 false)" }, "formats": { "type": "array", "items": { "type": "string" }, "description": "원본 제공 형식 목록" } } }, "description": "수동 자막 목록. 없으면 빈 배열" }, "automatic_captions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "auto": { "type": "boolean" }, "formats": { "type": "array", "items": { "type": "string" } }, "translated": { "type": "boolean", "description": "자동 번역 자막 여부. false 는 영상 원어의 음성 인식 자막입니다.자동 번역 자막은 유튜브 제한으로 내려받지 못할 수 있으니 원어 자막을 권장합니다." } } }, "description": "자동 생성 자막 목록. 항목 구조는 subtitles 와 같고 auto 는 true 입니다." }, "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", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "original_language": "en", "subtitle_count": 5, "automatic_caption_count": 157, "subtitles": [ { "lang": "en", "name": "English", "auto": false, "formats": [ "json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt" ] }, { "lang": "ja", "name": "Japanese", "auto": false, "formats": [ "json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt" ] } ], "automatic_captions": [ { "lang": "en-orig", "name": "English (Original)", "auto": true, "formats": [ "json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt" ], "translated": false }, { "lang": "ko", "name": "Korean", "auto": true, "formats": [ "json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt" ], "translated": true } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595636, "ms": 4180 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/youtube_subtitle_list' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'url=https://youtu.be/dQw4w9WgXcQ' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("url", "https://youtu.be/dQw4w9WgXcQ"); const response = await fetch("https://apick.app/rest/youtube_subtitle_list", { 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/dQw4w9WgXcQ")), ] response = requests.request("POST", "https://apick.app/rest/youtube_subtitle_list", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'https://youtu.be/dQw4w9WgXcQ', ]; $curl = curl_init('https://apick.app/rest/youtube_subtitle_list'); 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_subtitle_list API 호출 요청 요청하기 Key Value url 응답 ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터 video_id String 11자리 영상 ID title String 영상 제목 original_language String 영상 원어(음성 인식 자막 언어) 코드. 확인할 수 없으면 null subtitle_count Integer 수동 자막(채널이 올린 자막) 언어 수 automatic_caption_count Integer 자동 생성 자막 언어 수 (자동 번역 포함) subtitles Array 수동 자막 목록. 없으면 빈 배열 lang String 언어 코드. 자막 다운로드의 lang 값으로 사용합니다. name String 언어 이름. 없으면 null auto Boolean 자동 생성 여부 (subtitles 는 false) formats Array 원본 제공 형식 목록 automatic_captions Array 자동 생성 자막 목록. 항목 구조는 subtitles 와 같고 auto 는 true 입니다. translated Boolean 자동 번역 자막 여부. false 는 영상 원어의 음성 인식 자막입니다.자동 번역 자막은 유튜브 제한으로 내려받지 못할 수 있으니 원어 자막을 권장합니다. 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", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "original_language": "en", "subtitle_count": 5, "automatic_caption_count": 157, "subtitles": [ { "lang": "en", "name": "English", "auto": false, "formats": ["json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt"] }, { "lang": "ja", "name": "Japanese", "auto": false, "formats": ["json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt"] } ], "automatic_captions": [ { "lang": "en-orig", "name": "English (Original)", "auto": true, "formats": ["json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt"], "translated": false }, { "lang": "ko", "name": "Korean", "auto": true, "formats": ["json3", "srv1", "srv2", "srv3", "ttml", "srt", "vtt"], "translated": true } ], "success": 1 }, "api": { "success": true, "cost": 20, "pl_id": 1595636, "ms": 4180 } }