{"openapi":"3.0.3","info":{"title":"APICK 유튜브 자막 다운로드","version":"1.0.0","description":"공개 영상의 자막 한 언어를 VTT·SRT·텍스트 파일로 받습니다. 성공하면 응답 본문이 UTF-8 자막 파일 자체입니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/youtube_subtitle":{"post":{"summary":"유튜브 자막 다운로드","description":"공개 영상의 자막 한 언어를 VTT·SRT·텍스트 파일로 받습니다. 성공하면 응답 본문이 UTF-8 자막 파일 자체입니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"파일 직접 응답","content":{"text/vtt":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"조회할 유튜브 영상의 URL 또는 11자리 ID입니다. 예: https://youtu.be/dQw4w9WgXcQ 또는 dQw4w9WgXcQ. 재생목록·채널 URL은 영상 조회에 쓸 수 없습니다. (string)","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"lang":{"type":"string","description":"자막 언어 코드 (예: ko, en, en-US, en-orig). 자막 목록 조회 결과의 lang 값. 자동 번역 자막(translated=true)은 실패할 수 있어 원어 자막을 권장 (string)","example":"en"},"format":{"type":"string","description":"파일 형식 vtt(기본)·srt·txt. txt는 시간 정보를 뺀 본문만 반환합니다. (string)","example":"vtt"},"type":{"type":"string","description":"자막 종류 any(기본: 수동 자막 우선, 없으면 자동 생성)·manual·auto 가능한 값은 2가지입니다. any = 종류·기간을 제한하지 않는 값입니다. 가장 넓은 결과가 오므로 관련도가 낮은 항목도 포함됩니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. (string)"}},"required":["url","lang"]}}}}}}},"x-code-tables":[{"title":"format 허용값","columns":["값","용도·Content-Type"],"rows":[["vtt","웹 플레이어용 WebVTT (기본값). text/vtt; charset=utf-8"],["srt","영상 편집 프로그램용 SubRip. application/x-subrip; charset=utf-8"],["txt","요약·검색 등 텍스트 분석용. 시간 정보와 태그를 빼고 한 줄에 자막 한 줄씩 담으며, 바로 앞 줄과 같은 줄은 한 번만 남깁니다. text/plain; charset=utf-8"]]},{"title":"type 허용값","columns":["값","의미"],"rows":[["any","수동 자막을 먼저 찾고 없으면 자동 생성 자막을 줍니다 (기본값)."],["manual","업로더가 올린 수동 자막만 받습니다."],["auto","자동 생성 자막만 받습니다."]]},{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["영상 주소 오류","400","입력 항목이 잘못됐습니다. 유튜브 영상 주소 또는 11자리 영상 ID를 입력해 주세요.","영상 주소 형식이나 11자리 ID를 확인합니다."],["자막 조건 오류","400","입력 항목이 잘못됐습니다. lang(언어 코드), format(vtt·srt·txt), type(any·manual·auto)을 확인해 주세요.","lang을 빠뜨리지 않았는지, format·type이 허용값인지 확인합니다."],["영상 없음","404","영상을 찾을 수 없습니다. 삭제·비공개 영상이거나 잘못된 주소입니다.","주소와 공개 여부를 확인합니다."],["요청한 언어 자막 없음","404","요청한 언어의 자막을 찾을 수 없습니다. 자막 목록 조회로 제공 언어를 확인해 주세요.","자막 목록 조회의 lang 값을 그대로 보냅니다. type=manual로 요청했다면 any로 바꿔 봅니다."],["자막 받기 실패","424","자막을 가져오지 못했습니다. 자동 번역 자막(자막 목록의 translated=true)은 유튜브 제한으로 받지 못할 수 있으니 원어 자막을 이용하거나 잠시 후 다시 시도해 주세요.","원어 자막(translated가 false인 언어)으로 다시 요청합니다."],["연령 제한","403","연령 제한 영상은 조회할 수 없습니다.","연령 제한 영상은 제공하지 않습니다."],["회원 전용","403","채널 회원 전용 영상은 조회할 수 없습니다.","채널 회원 전용 영상은 제공하지 않습니다."],["시간 초과","408","처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."],["일시적 조회 실패","424","일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}