API Reference

YouTube Data API를 사용하면 일반적으로 YouTube 웹사이트에서 실행되는 함수를 자체 웹사이트 또는 애플리케이션에 통합할 수 있습니다. 아래 목록에는 API를 사용하여 검색할 수 있는 다양한 유형의 리소스가 나와 있습니다. 또한 API는 이러한 리소스를 여러 개 삽입, 업데이트 또는 삭제하는 메서드를 지원합니다.

이 참조 가이드에서는 API를 사용하여 이러한 모든 작업을 실행하는 방법을 설명합니다. 이 가이드는 리소스 유형별로 구성되어 있습니다. 리소스는 동영상, 재생목록, 구독 등 YouTube 환경의 일부를 구성하는 항목 유형을 나타냅니다. 가이드에서는 각 리소스 유형에 하나 이상의 데이터 표현을 나열하며 리소스는 JSON 객체로 표시됩니다. 또한 리소스 유형별로 지원되는 하나 이상의 메소드(LIST, POST, DELETE 등)와 함께 애플리케이션에서 이러한 메소드를 사용하는 방법에 대해 설명합니다.

API 호출

다음은 YouTube Data API 요청에 적용되는 요구 사항입니다.

1. 모든 요청은 API 키 (key 매개변수 사용)를 지정하거나 OAuth 2.0 토큰을 제공해야 합니다. API 키는 프로젝트의 Developer Console API 액세스 창에서 확인할 수 있습니다.

2. 모든 삽입, 업데이트 및 삭제 요청 시에는 반드시 인증 토큰을 전송해야 합니다. 또한 인증된 사용자의 비공개 데이터를 검색하는 모든 요청 시에도 인증 토큰을 전송해야 합니다.

   또한 리소스를 검색하는 일부 API 메서드는 승인이 필요한 매개변수를 지원하거나 요청이 승인될 때 추가 메타데이터를 포함할 수 있습니다. 예를 들어 사용자가 업로드한 동영상을 검색하는 요청에는 특정 사용자가 요청을 인증할 경우 비공개 동영상도 포함될 수 있습니다.

3. 이 API는 OAuth 2.0 인증 프로토콜을 지원합니다. OAuth 2.0 토큰은 다음 방법 중 하나로 제공할 수 있습니다.

   • access_token 쿼리 매개변수 사용: ?access_token=oauth2-token
   • HTTP Authorization 헤더 사용: Authorization: Bearer oauth2-token

   애플리케이션에서 OAuth 2.0 인증을 구현하는 방법에 관한 전체 안내는 인증 가이드를 참고하세요.

리소스 유형

활동

activity 리소스에는 특정 채널 또는 사용자가 YouTube에서 취한 액션에 관한 정보가 포함됩니다. 활동 피드에 보고되는 작업에는 동영상 평가, 동영상 공유, 동영상을 즐겨찾기로 표시, 동영상 업로드 등이 포함됩니다. 각 activity 리소스는 작업 유형, 작업과 연결된 채널, 작업과 연결된 리소스(예: 평가 또는 업로드된 동영상)를 식별합니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /activities	요청 기준과 일치하는 채널 활동 이벤트 목록을 반환합니다. 예를 들어 특정 채널 또는 사용자의 채널과 연결된 이벤트를 검색할 수 있습니다.
insert	POST /activities	참고: 이 메서드는 지원 중단되었으며 더 이상 지원되지 않습니다.

자막

caption 리소스는 YouTube 자막 트랙을 나타냅니다. 자막 트랙은 정확히 하나의 YouTube 동영상에 연결됩니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
delete	DELETE /captions	지정된 자막 트랙을 삭제합니다.
download	GET /captions/id	자막 트랙을 다운로드합니다. 요청에 tfmt 매개변수 값이 지정되지 않은 경우 자막 트랙은 원래 형식으로 반환되고, 요청에 tlang 매개변수 값이 지정되지 않은 경우 원래 언어로 반환됩니다.
insert	POST /captions	자막 트랙을 업로드합니다.
list	GET /captions	지정된 동영상과 연결된 자막 트랙 목록을 반환합니다. API 응답에는 실제 자막이 포함되지 않으며 captions.download 메서드는 자막 트랙을 검색하는 기능을 제공합니다.
update	PUT /captions	자막 트랙을 업데이트합니다. 자막 트랙을 업데이트할 때 트랙의 초안 상태를 변경하거나, 트랙의 새 자막 파일을 업로드하거나, 둘 다를 할 수 있습니다.

ChannelBanners

channelBanner 리소스에는 새로 업로드한 이미지를 채널의 배너 이미지로 설정하는 데 사용할 URL이 포함되어 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
insert	POST /channelBanners/insert	YouTube에 채널 배너 이미지를 업로드합니다. 이 메소드는 다음과 같이 채널의 배너 이미지를 업데이트하는 3단계 절차 중 처음 두 단계를 나타냅니다. channelBanners.insert 메서드를 호출하여 바이너리 이미지 데이터를 YouTube에 업로드합니다. 이미지의 가로세로 비율은 16:9여야 하며, 크기는 2048x1152픽셀 이상이어야 합니다. 2560x1440픽셀 이미지를 업로드하는 것이 좋습니다. 1단계에서 API가 반환하는 응답에서 url 속성 값을 추출합니다. channels.update 메서드를 호출하여 채널의 브랜딩 설정을 업데이트합니다. brandingSettings.image.bannerExternalUrl 속성 값을 2단계에서 가져온 URL로 설정합니다.

ChannelSections

channelSection 리소스에는 채널에서 추천으로 선택한 동영상 집합에 관한 정보가 포함됩니다. 예를 들어 섹션에는 채널의 최신 업로드 동영상, 가장 인기 있는 업로드 동영상 또는 하나 이상의 재생목록에 있는 동영상이 표시될 수 있습니다.

채널의 섹션은 채널이 피드 뷰가 아닌 둘러보기 뷰에 콘텐츠를 표시하는 경우에만 표시됩니다. 채널에서 둘러보기 보기에 콘텐츠를 표시하도록 하려면 지정된 채널의 brandingSettings.channel.showBrowseView 속성을 true로 설정합니다.

채널은 최대 10개의 섹션을 만들 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
delete	DELETE /channelSections	채널 섹션을 삭제합니다.
insert	POST /channelSections	인증된 사용자의 채널에 채널 섹션을 추가합니다. 채널은 최대 10개의 섹션을 만들 수 있습니다.
list	GET /channelSections	API 요청 기준과 일치하는 channelSection 리소스 목록을 반환합니다.
update	PUT /channelSections	채널 섹션을 업데이트합니다.

채널

channel 리소스에는 YouTube 채널에 관한 정보가 포함됩니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /channels	요청 기준과 일치하는 channel 리소스 0개 이상으로 구성된 컬렉션을 반환합니다.
update	PUT /channels	채널의 메타데이터를 업데이트합니다. 이 메서드는 현재 channel 리소스의 brandingSettings 및 invideoPromotion 객체와 하위 속성의 업데이트만 지원합니다.

CommentThreads

commentThread 리소스에는 YouTube 댓글 대화목록에 관한 정보가 포함되어 있습니다. 댓글 대화목록은 최상위 댓글과 해당 댓글에 대한 답글(있는 경우)로 구성됩니다. commentThread 리소스는 동영상 또는 채널에 대한 댓글을 나타낼 수 있습니다.

최상위 댓글과 답글은 실제로 commentThread 리소스 내에 중첩된 comment 리소스입니다. commentThread 리소스에 댓글에 대한 모든 답글이 포함되는 것은 아닙니다. 특정 댓글에 대한 모든 답글을 가져오려면 comments.list 메서드를 사용해야 합니다. 또한 일부 댓글에는 답글이 없습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /commentThreads	API 요청 매개변수와 일치하는 댓글 대화목록을 반환합니다.
insert	POST /commentThreads	새 최상위 주석을 만듭니다. 기존 댓글에 답글을 추가하려면 대신 comments.insert 메서드를 사용하세요.

댓글

comment 리소스에는 단일 YouTube 댓글에 관한 정보가 포함되어 있습니다. comment 리소스는 동영상 또는 채널에 대한 댓글을 나타낼 수 있습니다. 또한 댓글은 최상위 댓글이거나 최상위 댓글에 대한 답글일 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /comments	API 요청 매개변수와 일치하는 댓글 목록을 반환합니다.
setModerationStatus	POST /comments/setModerationStatus	하나 이상의 댓글의 검토 상태를 설정합니다. 댓글과 연결된 채널 또는 동영상의 소유자가 API 요청을 승인해야 합니다.
insert	POST /comments	기존 댓글에 대한 답글을 만듭니다. 참고: 최상위 주석을 만들려면 commentThreads.insert 메서드를 사용하세요.
markAsSpam	POST /comments/markAsSpam	참고: 이 메서드는 지원 중단되었으며 더 이상 지원되지 않습니다.
delete	DELETE /comments	댓글을 삭제합니다.
update	PUT /comments	댓글을 수정합니다.

GuideCategories

guideCategory 리소스는 채널의 콘텐츠 또는 채널의 인기도와 같은 기타 지표를 기반으로 YouTube에서 알고리즘을 통해 할당하는 카테고리를 식별합니다. 이 목록은 동영상 카테고리와 유사하지만, 동영상 카테고리는 동영상 업로더가 할당할 수 있지만 채널 카테고리는 YouTube만 할당할 수 있다는 점이 다릅니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /guideCategories	YouTube 채널과 관련된 카테고리의 목록을 반환합니다.

I18nLanguages

i18nLanguage 리소스는 YouTube 웹사이트에서 지원하는 애플리케이션 언어를 식별합니다. 애플리케이션 언어를 UI 언어라고도 합니다. YouTube 웹사이트의 경우 Google 계정 설정, 브라우저 언어 또는 IP 위치에 따라 애플리케이션 언어가 자동으로 선택될 수 있습니다. 사용자는 YouTube 사이트 바닥글에서 원하는 UI 언어를 직접 선택할 수도 있습니다.

각 i18nLanguage 리소스는 언어 코드와 이름을 식별합니다. 언어 코드는 videoCategories.list 및 guideCategories.list와 같은 API 메서드를 호출할 때 hl 매개변수의 값으로 사용할 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /i18nLanguages	YouTube 웹사이트에서 지원하는 애플리케이션 언어 목록을 반환합니다.

I18nRegions

i18nRegion 리소스는 YouTube 사용자가 선호하는 콘텐츠 지역으로 선택할 수 있는 지리적 영역을 식별합니다. 콘텐츠 지역은 콘텐츠 언어라고도 합니다. YouTube 웹사이트의 경우 YouTube 도메인 또는 사용자의 IP 위치와 같은 휴리스틱을 기반으로 콘텐츠 지역이 자동으로 선택될 수 있습니다. 사용자는 YouTube 사이트 바닥글에서 원하는 콘텐츠 지역을 직접 선택할 수도 있습니다.

각 i18nRegion 리소스는 지역 코드와 이름을 식별합니다. 지역 코드는 search.list, videos.list, activities.list, videoCategories.list와 같은 API 메서드를 호출할 때 regionCode 매개변수의 값으로 사용할 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /i18nRegions	YouTube 웹사이트에서 지원하는 콘텐츠 지역 목록을 반환합니다.

회원

member 리소스는 YouTube 채널의 채널 회원을 나타냅니다. 회원이 크리에이터에게 정기적으로 금전적 지원을 제공하고 특별한 혜택을 받습니다. 예를 들어 크리에이터가 채팅에 회원 전용 모드를 사용 설정하면 회원이 채팅할 수 있습니다.

이 리소스에 관한 자세한 내용은 리소스 표현 및 속성 목록을 참고하세요.

메서드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /members	채널의 회원 (이전 명칭: '스폰서') 목록을 표시합니다. API 요청은 채널 소유자의 승인을 받아야 합니다.

MembershipsLevels

membershipsLevel 리소스는 API 요청을 승인한 크리에이터의 가격 책정 수준을 식별합니다.

이 리소스에 관한 자세한 내용은 리소스 표현 및 속성 목록을 참고하세요.

메서드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /membershipsLevels	API 요청을 승인한 채널이 소유한 membershipsLevel 리소스 0개 이상을 모아 반환합니다. 수준은 암시적 표시 순서로 반환됩니다.

PlaylistItems

playlistItem 리소스는 재생목록에 포함된 동영상과 같은 다른 리소스를 식별합니다. 또한 playlistItem 리소스에는 해당 리소스가 재생목록에서 사용되는 방식과 관련된 포함된 리소스에 관한 세부정보가 포함됩니다.

YouTube는 재생목록을 사용하여 채널의 업로드된 동영상 목록을 식별하기도 합니다. 이 목록의 각 playlistItem는 업로드된 동영상 1개를 나타냅니다. 지정된 채널의 channel resource에서 해당 목록의 재생목록 ID를 검색할 수 있습니다. 그런 다음 목록에 playlistItems.list 메서드를 사용할 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
delete	DELETE /playlistItems	재생목록의 항목을 삭제합니다.
insert	POST /playlistItems	재생목록에 리소스를 추가합니다.
list	GET /playlistItems	API 요청 매개변수와 일치하는 재생목록 항목 모음을 반환합니다. 지정된 재생목록의 모든 항목을 검색하거나 고유 ID를 통해 하나 또는 여러 개의 재생목록 항목을 검색할 수 있습니다.
update	PUT /playlistItems	재생목록 항목을 수정합니다. 예를 들어 재생목록에서 항목의 위치를 업데이트할 수 있습니다.

재생목록

playlist 리소스는 YouTube 재생목록을 나타냅니다. 재생목록은 순차적으로 시청하고 다른 사용자와 공유할 수 있는 동영상 모음입니다. 재생목록은 기본적으로 다른 사용자에게 공개되지만 비공개로 설정할 수도 있습니다.

YouTube는 재생목록을 사용하여 채널의 다음과 같은 특별한 동영상 모음을 식별하기도 합니다.

• 업로드한 동영상
• 긍정적 평가(좋아요)를 받은 동영상
• 시청 기록
• 나중에 볼래

구체적으로 이러한 목록은 사람, 그룹 또는 회사의 동영상, 재생목록, 기타 YouTube 정보가 모인 채널과 연결됩니다. 지정된 채널의 channel resource에서 이러한 각 목록의 재생목록 ID를 가져올 수 있습니다.

그런 다음 playlistItems.list 메서드를 사용하여 이러한 목록을 가져올 수 있습니다. playlistItems.insert 및 playlistItems.delete 메서드를 호출하여 이러한 목록에 항목을 추가하거나 삭제할 수도 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
delete	DELETE /playlists	재생목록을 삭제합니다.
list	GET /playlists	API 요청 매개변수와 일치하는 재생목록 모음을 반환합니다. 예를 들어 인증된 사용자가 보유한 전체 재생목록을 검색하거나, 고유 ID를 통해 하나 또는 여러 개의 재생목록을 검색할 수 있습니다.
insert	POST /playlists	재생목록을 만듭니다.
update	PUT /playlists	재생목록을 수정합니다. 예를 들어 재생목록의 제목, 설명, 개인정보 보호 상태를 변경할 수 있습니다.

검색

검색결과에는 API 요청에 지정된 검색 매개변수와 일치하는 YouTube 동영상, 채널 또는 재생목록의 정보가 포함되어 있습니다. 검색결과는 동영상과 같이 고유하게 식별할 수 있는 리소스를 보여주지만, 자체적으로는 영구적인 데이터를 가지지 않습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /search	API 요청에 지정된 쿼리 매개변수와 일치하는 검색 결과 컬렉션을 반환합니다. 기본적으로 검색 결과 세트는 일치하는 video, channel, playlist 리소스를 식별하지만 특정 유형의 리소스만 검색하도록 쿼리를 구성할 수도 있습니다.

구독

subscription 리소스에는 YouTube 사용자 구독에 대한 정보가 포함되어 있습니다. 구독정보는 채널에 새 동영상이 추가되거나 다른 사용자가 YouTube에서 동영상 업로드, 동영상 평가 또는 동영상 추천 등의 작업 중 하나를 수행할 때 이를 알려줍니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
delete	DELETE /subscriptions	구독정보를 삭제합니다.
insert	POST /subscriptions	인증된 사용자 채널에 대한 구독정보를 추가합니다.
list	GET /subscriptions	API 요청 기준과 일치하는 구독정보 리소스를 반환합니다.

썸네일

thumbnail 리소스는 리소스와 연결된 다양한 썸네일 이미지 크기를 식별합니다. 미리보기 이미지의 특징은 다음과 같습니다.

• 리소스의 snippet.thumbnails 속성은 해당 리소스에 사용할 수 있는 썸네일 이미지를 식별하는 객체입니다.
• thumbnail 리소스에는 일련의 객체가 포함되어 있습니다. 각 객체의 이름 (default, medium, high 등)은 썸네일 이미지 크기를 나타냅니다.
• 다양한 유형의 리소스를 통해 미리보기 이미지의 다양한 크기를 지원할 수 있습니다.
• 리소스 유형에 따라 동일한 이름의 썸네일 이미지에 서로 다른 크기가 정의될 수 있습니다. 예를 들어 video 리소스의 default 썸네일 이미지는 일반적으로 120px x 90px이고 channel 리소스의 default 썸네일 이미지는 일반적으로 88px x 88px입니다.
• 동일한 유형의 리소스라도 YouTube에 업로드된 원본 이미지 또는 콘텐츠의 해상도에 따라 특정 이미지의 썸네일 이미지 크기가 다를 수 있습니다. 예를 들어 HD 동영상은 HD가 아닌 동영상보다 더 높은 해상도의 미리보기를 지원할 수 있습니다.
• 썸네일 이미지 크기에 관한 정보를 포함하는 각 객체에는 width 속성과 height 속성이 있습니다. 하지만 width와 height 속성은 반환되지 않을 수도 있습니다.
• 업로드된 썸네일 이미지가 필요한 크기와 일치하지 않으면 가로세로 비율을 변경하지 않고 올바른 크기에 맞게 이미지 크기가 조정됩니다. 이미지가 잘리지는 않으나 올바른 크기로 맞추기 위해 이미지에 검은색 띠가 포함될 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
set	POST /thumbnails/set	YouTube에 맞춤 동영상 미리보기 이미지를 업로드하고 이를 동영상에 설정합니다.

VideoAbuseReportReasons

videoAbuseReportReason 리소스에는 동영상에 악성 콘텐츠가 포함되어 신고된 이유에 관한 정보가 포함됩니다. 애플리케이션이 videos.reportAbuse 메서드를 호출하여 악성 동영상을 신고하면 요청은 videoAbuseReportReason 리소스의 정보를 사용하여 동영상이 신고되는 이유를 식별합니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /videoAbuseReportReasons	악성 동영상을 신고하는 데 사용할 수 있는 이유 목록을 가져옵니다.

VideoCategories

videoCategory 리소스는 업로드된 동영상과 연결되었거나 연결될 수 있는 카테고리를 식별합니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
list	GET /videoCategories	YouTube 동영상과 연결할 수 있는 카테고리의 목록을 반환합니다.

동영상

video 리소스는 YouTube 동영상을 나타냅니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
insert	POST /videos	YouTube에 동영상을 업로드하고 동영상의 메타데이터를 선택적으로 설정합니다.
list	GET /videos	API 요청 매개변수와 일치하는 동영상의 목록을 반환합니다.
delete	DELETE /videos	YouTube 동영상을 삭제합니다.
update	PUT /videos	동영상의 메타데이터를 업데이트합니다.
rate	POST /videos/rate	동영상에 좋아요 또는 싫어요 평가를 추가하거나 이러한 평가를 삭제합니다.
getRating	GET /videos/getRating	지정된 동영상의 목록에 대해 인증된 사용자가 적용한 평가를 검색합니다.
reportAbuse	POST /videos/reportAbuse	악성 콘텐츠가 포함된 동영상을 신고합니다.

워터마크

watermark 리소스는 지정된 채널의 동영상 재생 중에 표시되는 이미지를 식별합니다. 또한 동영상 재생 중 워터마크가 표시되는 시기와 표시되는 시간의 길이를 정하는 타이밍 세부정보뿐 아니라 이미지가 연결되는 타겟 채널도 지정할 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드	HTTP 요청	설명
https://www.googleapis.com/youtube/v3를 기준으로 하는 URI
set	POST /watermarks/set	워터마크 이미지를 YouTube에 업로드하고 채널에 설정합니다.
unset	POST /watermarks/unset	채널의 워터마크 이미지를 삭제합니다.