메인 콘텐츠로 건너뛰기
공개 YouTube 데이터를 비동기 task API로 JSON으로 읽습니다. taskType SOCIAL에 platform youtube를 보내고 action으로 읽을 대상을 고릅니다. 완료된 요청당 0.5크레딧입니다.

요청

task를 제출한 뒤 GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task.

동작

videoId는 동영상 ID나 YouTube 동영상 URL(시청 페이지, youtu.be, Shorts, 퍼가기)을 받습니다. channel은 채널 ID(UC...), @handle, 채널 URL을 받습니다.

입력

search와 recent:
  • query: 필수. 검색어입니다.
  • limit: 선택. 정수 1-50이며 기본값은 10입니다.
  • type: video(기본값), all, shorts, channel, playlist, movie 중 하나입니다.
  • order: relevance(기본값), viewCount, date, rating 중 하나입니다. date는 recent처럼 최신 업로드부터 나열합니다. rating은 YouTube의 조회수 상위 결과를 좋아요 수로 정렬합니다. channel과 playlist 검색은 relevance나 viewCount를 받습니다.
  • publishedAfter: 2026-11-01T00:00:00Z 같은 ISO 8601 시각입니다. 이 시각 뒤에 게시된 동영상을 돌려줍니다.
  • videoDuration: short(3분 미만), medium(3-20분), long(20분 초과) 중 하나입니다.
  • features: live, 4k, hd, subtitles, creative_commons, 360, vr180, 3d, hdr, location, purchased 중 원하는 값을 배열이나 쉼표로 구분한 문자열로 보냅니다.
  • exactSpelling: true이면 YouTube의 맞춤법 교정 없이 입력한 그대로 검색합니다.
  • pageToken: 이전 페이지의 nextPageToken입니다. publishedAfter 없이 relevance나 viewCount로 정렬한 동영상 검색이 이 값을 돌려주며, 각 페이지는 앞 페이지들이 돌려준 동영상을 모두 건너뜁니다.
  • regionCode와 languageCode: 검색할 YouTube 지역(US, KR, JP)과 인터페이스 언어(en, ko, ja)입니다.
comments:
  • limit: 선택. 정수 1-500이며 기본값은 100입니다. 답글도 개수에 포함됩니다.
  • order: relevance(기본값, YouTube의 인기 댓글)나 time(최신순)입니다.
  • includeReplies: 선택. 기본값은 true입니다.
channel_videos:
  • tab: videos(기본값), shorts, streams 중 하나입니다.
  • sort: latest(기본값), popular, oldest 중 하나입니다.
  • limit: 선택. 정수 1-50이며 기본값은 20입니다.
transcript:
  • languages: ["en", "ko"]처럼 원하는 순서로 나열한 자막 언어입니다. 없으면 동영상의 기본 자막, 영어 자막, 첫 번째 트랙 순으로 읽습니다.
  • isGenerated: true이면 자동 생성 자막만, false이면 업로더가 올린 자막만 읽습니다.
  • trackName: 읽을 자막 트랙의 이름입니다.
  • translateTo: 언어 코드입니다. YouTube가 자막을 이 언어로 번역합니다.
  • maxSegments: 선택. 정수 1-5,000이며 기본값은 2,000입니다.

응답 예시

결과 필드

  • 모든 응답은 platform과 action을 그대로 돌려줍니다. 목록에는 returnedCount가 있습니다.
  • search와 recent는 videos를 돌려줍니다. 각 동영상에는 position, videoId, url, title, description, 채널의 channelId, channelTitle, channelHandle, channelUrl, channelThumbnail, channelIsVerified, publishedAt, publishedTimeText, duration(ISO 8601), durationSeconds, viewCount, likeCount, category, thumbnails, richThumbnail(움직이는 미리보기), badges, isFamilySafe가 있습니다. 영화에는 포스터, 장르, 연도, 출연진, 감독을 담은 movie가 더해집니다.
  • 검색은 결과 페이지에 보이는 channels, playlists, shorts, shelves와 totalResults(YouTube의 추정치)도 돌려주고, YouTube가 검색어를 교정하면 didYouMean이나 showingResultsFor를 돌려줍니다.
  • video는 tags, commentCount, subscriberCount, hasCaptions, chapters, mostReplayed, music, descriptionLinks, relatedVideos를 더합니다. 업로더가 만든 챕터가 먼저 오고, 자동 챕터에는 autoGenerated: true가 붙습니다.
  • comments는 comments를 돌려줍니다. 각 댓글에는 commentId, parentId(최상위 댓글은 null), text, authorDisplayName, authorChannelId, authorProfileImageUrl, authorIsVerified, authorIsChannelOwner, isPinned, isHearted, likeCount, replyCount, publishedAt, updatedAt이 있습니다. totalCount는 YouTube가 보여 주는 댓글 수이고, topLevelCount와 replyCount는 returnedCount를 나눈 값입니다.
  • channel은 channelId, title, handle, description, country, publishedAt, subscriberCount, videoCount, viewCount, isVerified, keywords, links, thumbnails, bannerUrl, rssUrl, uploadsPlaylistId를 돌려줍니다.
  • channel_videos는 sort 순서의 videos와 채널의 channelId, channelTitle을 돌려줍니다.
  • transcript는 자막 text, 시간이 붙은 segments(start와 duration, 초 단위), 읽은 language, availableLanguages를 돌려줍니다. truncated: true는 maxSegments에서 잘린 자막입니다.
  • 좋아요 수를 숨긴 동영상에는 likesHidden: true, 댓글을 끈 동영상에는 commentsDisabled: true가 붙습니다. 회원 전용 동영상에는 membersOnly: true가 붙고 viewCount가 없습니다.
  • 없는 동영상, 채널, 자막 트랙이나 연령 제한 동영상처럼 로그인한 시청자만 볼 수 있는 대상은 task를 PAGE_UNAVAILABLE로 끝냅니다. 함께 쓸 수 없는 파라미터는 task를 BAD_PAYLOAD로 끝냅니다. 완료된 요청만 과금합니다.

관련 문서