{"openapi":"3.0.3","info":{"title":"APICK 유튜브 댓글 조회","version":"1.0.0","description":"공개 영상의 댓글을 인기순 또는 최신순으로 받습니다. 작성자·본문·좋아요 수·고정·하트 여부가 함께 오며, 원하면 답글도 함께 받습니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/youtube_comments":{"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자리)입니다."},"title":{"type":"string","description":"영상 제목입니다."},"sort":{"type":"string","description":"적용한 정렬(top·new)입니다."},"include_replies":{"type":"boolean","description":"답글을 포함했는지 여부입니다."},"count":{"type":"integer","description":"이번 응답에 담긴 댓글 수(답글 포함)입니다."},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"댓글 ID입니다. 중복 확인 키로 씁니다."},"parent_id":{"nullable":true,"type":"string","description":"답글이면 부모 댓글 ID, 최상위 댓글이면 null입니다."},"text":{"type":"string","description":"댓글 본문입니다."},"author":{"type":"string","description":"작성자 표시 이름입니다. 없으면 null입니다.","nullable":true},"author_channel_id":{"type":"string","description":"작성자 채널 ID(UC…)입니다. 없으면 null입니다.","nullable":true},"author_url":{"type":"string","description":"작성자 채널 주소입니다. 없으면 null입니다.","nullable":true},"author_thumbnail":{"type":"string","description":"작성자 프로필 이미지 주소입니다. 없으면 null입니다.","nullable":true},"author_is_uploader":{"type":"boolean","description":"영상 게시자 본인의 댓글이면 true입니다."},"author_is_verified":{"type":"boolean","description":"인증 채널 작성자면 true입니다."},"like_count":{"type":"integer","description":"좋아요 수입니다. 확인할 수 없으면 null입니다.","nullable":true},"is_pinned":{"type":"boolean","description":"고정 댓글이면 true입니다."},"is_hearted":{"type":"boolean","description":"게시자가 하트를 남긴 댓글이면 true입니다."},"published_at":{"type":"string","description":"작성 시각(ISO 8601)입니다. 날짜 단위 근삿값이며 없으면 null입니다.","nullable":true}}},"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://youtu.be/dQw4w9WgXcQ 또는 dQw4w9WgXcQ. 재생목록·채널 URL은 영상 조회에 쓸 수 없습니다. (string)","example":"https://www.youtube.com/watch?v=9bZkp7q19f0"},"count":{"type":"string","description":"받을 댓글 수 1~200 (기본 20, 답글 포함) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (integer)","example":"20"},"sort":{"type":"string","description":"top(인기순, 기본)·new(최신순) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 2가지입니다. top = 인기·상위 항목을 먼저 보여 주는 정렬 값입니다. new = 최신 항목을 먼저 보여 주는 정렬 값입니다. (string)","enum":["top","new"],"example":"top"},"replies":{"type":"string","description":"true면 댓글마다 답글을 최대 5개까지 함께 받습니다 (기본 false) true = 댓글마다 답글을 최대 5개까지 함께 받도록 요청한 경우, false 또는 생략 = 답글 없이 최상위 댓글만 받는 경우입니다. 켜면 응답 크기와 처리 시간이 늘어납니다. (boolean)"}},"required":["url"]}}}}}}},"x-code-tables":[{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["영상 주소 오류","400","입력 항목이 잘못됐습니다. 유튜브 영상 주소 또는 11자리 영상 ID를 입력해 주세요.","영상 주소 형식이나 11자리 ID를 확인합니다."],["조회 조건 오류","400","입력 항목이 잘못됐습니다. count(1~200), sort(top·new), replies(true·false)를 확인해 주세요.","count를 1~200 정수로, sort·replies를 허용값으로 보냅니다."],["영상 없음","404","영상을 찾을 수 없습니다. 삭제·비공개 영상이거나 잘못된 주소입니다.","주소와 공개 여부를 확인합니다."],["연령 제한","403","연령 제한 영상은 조회할 수 없습니다.","연령 제한 영상은 제공하지 않습니다."],["회원 전용","403","채널 회원 전용 영상은 조회할 수 없습니다.","채널 회원 전용 영상은 제공하지 않습니다."],["시간 초과","408","처리 시간 초과로 실패했습니다. 잠시 후 다시 시도해 주세요.","count를 줄이거나 replies=false로 다시 보냅니다."],["일시적 조회 실패","424","일시적으로 영상 정보를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}