{"openapi":"3.0.3","info":{"title":"APICK 유튜브 영상 정보 조회","version":"1.0.0","description":"공개 영상 하나의 제목·설명·채널·길이·조회수·좋아요·댓글 수·업로드일·태그·챕터·썸네일과 제공 자막 언어를 한 번에 받습니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/youtube_metadata":{"post":{"summary":"유튜브 영상 정보 조회","description":"공개 영상 하나의 제목·설명·채널·길이·조회수·좋아요·댓글 수·업로드일·태그·챕터·썸네일과 제공 자막 언어를 한 번에 받습니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"video_id":{"type":"string","description":"영상 ID(11자리)입니다."},"url":{"type":"string","description":"표준 영상 주소(watch?v=)입니다."},"title":{"type":"string","description":"제목입니다."},"description":{"type":"string","description":"영상 설명 전문입니다. 없으면 빈 문자열입니다."},"channel":{"type":"object","properties":{"id":{"type":"string","description":"채널 ID(UC…)입니다."},"name":{"type":"string","description":"채널 이름입니다."},"url":{"type":"string","description":"채널 주소입니다."},"handle":{"type":"string","description":"채널 핸들입니다. 없으면 null입니다.","nullable":true},"follower_count":{"type":"integer","description":"구독자 수입니다. 숨긴 채널은 null입니다.","nullable":true},"is_verified":{"type":"boolean","description":"인증 채널 여부입니다."}}},"upload_date":{"type":"string","description":"업로드일(YYYY-MM-DD)입니다. 모르면 null입니다.","nullable":true},"duration":{"type":"integer","description":"영상 길이(초)입니다. 라이브 중이거나 모르면 null입니다.","nullable":true},"view_count":{"type":"integer","description":"조회수입니다. 확인할 수 없으면 null입니다.","nullable":true},"like_count":{"type":"integer","description":"좋아요 수입니다. 숨긴 영상은 null입니다.","nullable":true},"comment_count":{"type":"integer","description":"댓글 수입니다. 댓글이 꺼졌거나 확인할 수 없으면 null입니다.","nullable":true},"categories":{"type":"array","items":{"type":"string"},"description":"카테고리 이름 목록입니다. 예: Music"},"tags":{"type":"array","items":{"type":"string"},"description":"업로더가 단 태그 목록입니다."},"language":{"type":"string","description":"영상 언어 코드입니다. 모르면 null입니다.","nullable":true},"live_status":{"type":"string","description":"not_live·is_live·is_upcoming·was_live·post_live 중 하나입니다. 모르면 null입니다.","nullable":true},"availability":{"type":"string","description":"공개 범위입니다. public(공개)·unlisted(링크를 아는 사람만) 등이며 모르면 null입니다.","nullable":true},"age_limit":{"type":"integer","description":"시청 연령 제한입니다. 0이면 제한이 없습니다."},"chapters":{"type":"array","items":{},"description":"챕터 목록입니다. 항목마다 title·start_time(초)·end_time(초)이 옵니다. 챕터가 없으면 빈 배열입니다."},"thumbnail":{"type":"string","description":"가장 큰 썸네일 주소입니다."},"thumbnails":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}}},"description":"썸네일 목록입니다. 큰 순서이며 항목마다 url·width·height가 옵니다."},"subtitle_languages":{"type":"array","items":{"type":"string"},"description":"업로더가 올린 수동 자막의 언어 코드 목록입니다. 자막 다운로드의 lang에 그대로 씁니다."},"automatic_caption_count":{"type":"integer","description":"자동 생성 자막 언어 수입니다. 목록은 유튜브 자막 목록 조회로 받습니다."},"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":"결제 기록 번호입니다. 성공한 응답에만 옵니다."}}}}}}}},"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://www.youtube.com/watch?v=..., https://youtu.be/..., /shorts/...) (string)","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}},"required":["url"]}}}}}}},"x-code-tables":[{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["입력 오류","400","입력 항목이 잘못됐습니다. 유튜브 영상 주소 또는 11자리 영상 ID를 입력해 주세요.","영상 주소 형식이나 11자리 ID를 확인합니다. 재생목록·채널 주소는 각 조회 API를 씁니다."],["영상 없음","404","영상을 찾을 수 없습니다. 삭제·비공개 영상이거나 잘못된 주소입니다.","삭제·비공개·지역 제한 영상입니다. 시작 전 예약 방송도 이 응답이 올 수 있습니다. 주소와 공개 여부를 확인합니다."],["연령 제한","403","연령 제한 영상은 조회할 수 없습니다.","연령 제한 영상은 제공하지 않습니다. 다른 영상을 요청합니다."],["회원 전용","403","채널 회원 전용 영상은 조회할 수 없습니다.","채널 회원 전용 영상은 제공하지 않습니다."],["시간 초과","408","처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."],["일시적 조회 실패","424","일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}