# 유튜브 자막 목록 조회 공개 영상에서 받을 수 있는 자막 언어를 수동 자막과 자동 생성 자막으로 나눠 알려 줍니다. 자막 본문은 오지 않으며, 응답의 lang 값을 유튜브 자막 다운로드의 lang에 그대로 넣습니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/youtube_subtitle_list 응답 필드 - `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다. - `data.video_id` (string): 영상의 고유 ID입니다. 같은 영상을 다시 조회해도 같은 값이 오며, 요청에서 지정한 영상 ID를 그대로 반환합니다. - `data.title` (string): 영상 제목입니다. 대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다. - `data.original_language` (string): 영상 원어 코드입니다. 확인할 수 없으면 null입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용. - `data.subtitle_count` (integer): 수동 자막 언어 수입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.automatic_caption_count` (integer): 자동 생성 자막이 제공되는 언어의 수입니다. 0이면 자동 자막이 없습니다. - `data.subtitles` (array): 사용자가 직접 등록한 자막 목록입니다. 언어별로 형식 정보가 들어 있습니다. - `data.subtitles[].lang` (string): 언어 코드입니다. 자막 다운로드의 lang에 그대로 넣습니다. 예: en, ko, en-US - `data.subtitles[].name` (string): 언어 이름입니다. 없으면 null입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용. - `data.subtitles[].auto` (boolean): 수동 자막은 항상 false입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 음성 인식으로 자동 생성된 자막인 경우, false = 제작자가 직접 올린 자막인 경우입니다. - `data.subtitles[].formats` (array): 원본에서 제공하는 자막 형식 이름 목록입니다. 다운로드 형식은 자막 다운로드의 format으로 고릅니다. - `data.automatic_captions` (array): 자동 생성 자막 목록입니다. 언어별로 형식과 번역 여부가 들어 있습니다. - `data.automatic_captions[].lang` (string): 자막 언어 코드입니다. 예: ko, en-orig. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.automatic_captions[].name` (string): 자막의 표시 이름입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.automatic_captions[].auto` (boolean): 자동 생성 자막인지 여부입니다. true면 음성 인식으로 만들어진 자막입니다. true = 음성 인식으로 자동 생성된 자막인 경우, false = 제작자가 직접 올린 자막인 경우입니다. - `data.automatic_captions[].formats` (array): 내려받을 수 있는 자막 형식 목록입니다. 원하는 형식을 골라 자막 다운로드 경로에 지정합니다. - `data.automatic_captions[].translated` (boolean): 자동 번역 자막이면 true, 영상 원어의 음성 인식 자막이면 false입니다. -orig로 끝나는 lang(예: en-orig)과 같은 언어의 lang(예: en)이 원어 자막입니다. 원어를 확인할 수 없는 영상은 모두 false로 옵니다. true = 다른 언어로 자동 번역된 자막인 경우, false = 영상 원어 그대로의 자막인 경우입니다. - `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요. - `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다. - `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다. - `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다. - `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다. - `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. ## API 요청: POST /rest/youtube_subtitle_list ### 입력 - `url` (string, 필수): 조회할 유튜브 영상의 URL 또는 11자리 ID입니다. 예: https://youtu.be/dQw4w9WgXcQ 또는 dQw4w9WgXcQ. 재생목록·채널 URL은 영상 조회에 쓸 수 없습니다. ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "video_id": { "type": "string", "description": "영상 ID(11자리)입니다." }, "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에 그대로 넣습니다. 예: en, ko, en-US" }, "name": { "type": "string", "description": "언어 이름입니다. 없으면 null입니다.", "nullable": true }, "auto": { "type": "boolean", "description": "수동 자막은 항상 false입니다." }, "formats": { "type": "array", "items": { "type": "string" }, "description": "원본에서 제공하는 자막 형식 이름 목록입니다. 다운로드 형식은 자막 다운로드의 format으로 고릅니다." } } }, "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": "자동 번역 자막이면 true, 영상 원어의 음성 인식 자막이면 false입니다. -orig로 끝나는 lang(예: en-orig)과 같은 언어의 lang(예: en)이 원어 자막입니다. 원어를 확인할 수 없는 영상은 모두 false로 옵니다." } } }, "description": "자동 생성 자막 목록입니다. 항목 형식은 subtitles[]와 같고 auto가 true이며 translated가 더 붙습니다." }, "success": { "type": "integer", "description": "성공이면 1입니다." } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer", "description": "차감된 포인트입니다. 실패하면 0입니다." }, "ms": { "type": "integer", "description": "처리 시간(밀리초)입니다." }, "pl_id": { "type": "integer", "description": "결제 기록 번호입니다. 성공한 응답에만 옵니다." } } } } } ``` ### 정적 응답 예시 ```json { "data": { "video_id": "dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video)", "original_language": "en", "subtitle_count": 2, "automatic_caption_count": 2, "subtitles": [ { "lang": "en", "name": "English", "auto": false, "formats": [ "vtt", "srv3" ] }, { "lang": "ja", "name": "Japanese", "auto": false, "formats": [ "vtt", "srv3" ] } ], "automatic_captions": [ { "lang": "en-orig", "name": "English (Original)", "auto": true, "formats": [ "vtt" ], "translated": false }, { "lang": "ko", "name": "Korean", "auto": true, "formats": [ "vtt" ], "translated": true } ], "success": 1 }, "api": { "success": true, "cost": 20, "ms": 3700, "pl_id": 1595635 } } ``` ### 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://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_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://www.youtube.com/watch?v=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://www.youtube.com/watch?v=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); ``` ## 사용 예시 1. 제공 자막 언어 확인 자막을 내려받기 전에 어떤 언어가 있는지 확인합니다. ```bash 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' ``` - `data.subtitles[]`는 업로더가 올린 수동 자막, `data.automatic_captions[]`는 자동 생성 자막입니다. - 각 항목의 `lang` 값을 자막 다운로드 API의 `lang`에 그대로 넣습니다. ## 사용 예시 2. 원어 자동 자막 고르기 수동 자막이 없는 영상에서 음성 인식 원어 자막을 고를 때 씁니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/youtube_subtitle_list' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'url=dQw4w9WgXcQ' ``` - `data.original_language`가 영상 원어입니다. `automatic_captions[]` 중 `translated`가 false인 언어를 고르세요. - `translated`가 true인 자동 번역 자막은 다운로드에 실패할 수 있습니다. 원어 자막을 받은 뒤 직접 번역하는 편이 안정적입니다. - `data.subtitle_count`와 `automatic_caption_count`가 모두 0이면 자막이 없는 영상입니다. ## 코드·오류 ### 업무 실패 응답 입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요. ```json { "data": { "error": "입력값을 확인해 주세요.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 5 } } ``` ## 상세 기능·요금 이용 전 확인 성공한 조회 한 건당 20P가 차감됩니다. 실제 차감액은 응답의 api.cost에서 확인하세요. 입력 오류·영상 없음·연령 제한·회원 전용·시간 초과처럼 실패한 호출은 data.error로 안내 문구가 오고 과금되지 않습니다(api.cost 0). 자막이 하나도 없는 영상도 정상 응답(개수 0)이라 과금됩니다. 언어 고르는 순서: ① 원하는 언어의 수동 자막 → ② translated가 false인 자동 생성 자막(영상 원어) → ③ 자동 번역 자막(translated가 true, 다운로드에 실패할 수 있음). 응답 시간은 보통 6초 이내이고 최대 약 60초입니다. 요청 시간 제한을 90초 이상으로 잡으세요. 인증키는 서버 환경변수에 보관하고 공개 저장소·웹페이지에 넣지 마세요. API 호출 요청 요청하기 Key Value url 응답 ## 상세 요청 항목설정 메서드·주소POST https://apick.app/rest/youtube_subtitle_list 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data 요청 예시 영상 주소로 제공 자막을 확인하는 예입니다. 성공 시 과금되는 실제 요청입니다. form-data 전체 예제 보기 ## 상세 응답 필드타입설명 data.video_idstring영상 ID(11자리)입니다. data.titlestring영상 제목입니다. data.original_languagestring영상 원어 코드입니다. 확인할 수 없으면 null입니다. data.subtitle_countinteger수동 자막 언어 수입니다. data.automatic_caption_countinteger자동 생성 자막 언어 수입니다. data.subtitles[]array업로더가 올린 수동 자막 목록입니다. 언어 코드순입니다. data.subtitles[].langstring언어 코드입니다. 자막 다운로드의 lang에 그대로 넣습니다. 예: en, ko, en-US data.subtitles[].namestring언어 이름입니다. 없으면 null입니다. data.subtitles[].autoboolean수동 자막은 항상 false입니다. data.subtitles[].formats[]array원본에서 제공하는 자막 형식 이름 목록입니다. 다운로드 형식은 자막 다운로드의 format으로 고릅니다. data.automatic_captions[]array자동 생성 자막 목록입니다. 항목 형식은 subtitles[]와 같고 auto가 true이며 translated가 더 붙습니다. data.automatic_captions[].translatedboolean자동 번역 자막이면 true, 영상 원어의 음성 인식 자막이면 false입니다. -orig로 끝나는 lang(예: en-orig)과 같은 언어의 lang(예: en)이 원어 자막입니다. 원어를 확인할 수 없는 영상은 모두 false로 옵니다. data.successinteger성공이면 1입니다. api.costinteger차감된 포인트입니다. 실패하면 0입니다. api.msinteger처리 시간(밀리초)입니다. api.pl_idinteger결제 기록 번호입니다. 성공한 응답에만 옵니다. subtitle_count와 automatic_caption_count가 모두 0이면 자막이 없는 영상이니 자막 다운로드를 요청하지 마세요. 같은 언어가 수동·자동 생성 자막에 모두 있으면 자막 다운로드의 type으로 어느 쪽을 받을지 고릅니다(기본은 수동 자막 우선). { "data": { "video_id": "dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video)", "original_language": "en", "subtitle_count": 2, "automatic_caption_count": 2, "subtitles": [ { "lang": "en", "name": "English", "auto": false, "formats": ["vtt", "srv3"] }, { "lang": "ja", "name": "Japanese", "auto": false, "formats": ["vtt", "srv3"] } ], "automatic_captions": [ { "lang": "en-orig", "name": "English (Original)", "auto": true, "formats": ["vtt"], "translated": false }, { "lang": "ko", "name": "Korean", "auto": true, "formats": ["vtt"], "translated": true } ], "success": 1 }, "api": { "success": true, "cost": 20, "ms": 3700, "pl_id": 1595635 } } 예시는 길이를 줄이려고 자동 생성 자막을 두 개만 적었습니다. ## 상세 코드·정책 오류와 복구 아래 경우는 data.error로 응답하며 과금되지 않습니다(api.cost 0). 실패 응답은 표의 HTTP 상태 코드와 함께 옵니다. 화면에 보여 줄 안내는 본문의 data.error를 쓰세요. 상황HTTPdata.error해결 입력 오류400입력 항목이 잘못됐습니다. 유튜브 영상 주소 또는 11자리 영상 ID를 입력해 주세요.영상 주소 형식이나 11자리 ID를 확인합니다. 영상 없음404영상을 찾을 수 없습니다. 삭제·비공개 영상이거나 잘못된 주소입니다.주소와 공개 여부를 확인합니다. 연령 제한403연령 제한 영상은 조회할 수 없습니다.연령 제한 영상은 제공하지 않습니다. 회원 전용403채널 회원 전용 영상은 조회할 수 없습니다.채널 회원 전용 영상은 제공하지 않습니다. 시간 초과408처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다. 일시적 조회 실패424일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.잠시 후 같은 요청을 다시 보냅니다. ## 상세 예제 호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기