taskType SOCIAL에 platform youtube를 보내고 action으로 읽을 대상을 고릅니다. 완료된 요청당 0.5크레딧입니다.
요청
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로 끝냅니다. 완료된 요청만 과금합니다.