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 키는 프로젝트에 대한 개발자 콘솔의 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 자막 트랙을 다운로드합니다. 요청이 tlang 매개변수의 값을 지정하지 않는 한 요청이 tfmt 매개변수의 값을 원래 언어로 지정하지 않는 한 자막 트랙은 원래 형식으로 반환됩니다.
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단계 절차 중 처음 두 단계를 나타냅니다.

  1. channelBanners.insert 메서드를 호출하여 바이너리 이미지 데이터를 YouTube에 업로드합니다. 이미지는 가로세로 비율이 16:9이며 2048x1152픽셀 이상이어야 합니다. 2560x1440픽셀 이미지를 업로드하는 것이 좋습니다.
  2. API가 1단계에서 반환한 응답에서 url 속성의 값을 추출합니다.
  3. 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 요청 기준과 일치하는 0개 이상의 channel 리소스 모음을 반환합니다.
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 요청을 승인한 채널에서 소유한 0개 이상의 membershipsLevel 리소스 컬렉션을 반환합니다. 레벨은 암시적 표시 순서로 반환됩니다.

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 재생목록을 나타냅니다. 재생목록은 순서대로 감상하거나 다른 사용자와 공유할 수 있는 동영상의 모음입니다. 재생목록에는 최대 200개의 동영상을 포함할 수 있으며 YouTube는 각 사용자가 만들 수 있는 재생목록의 수를 제한하지 않습니다. 재생목록은 기본적으로 다른 사용자에게 공개되지만 비공개로 설정할 수도 있습니다.

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

  • 업로드한 동영상
  • 긍정적 평가(좋아요)를 받은 동영상
  • 시청 기록
  • 나중에 볼래
더 구체적으로 말하면 이러한 목록은 개인, 그룹 또는 회사의 동영상, 재생목록 및 기타 YouTube 정보의 모음인 채널과 연결되어 있습니다. 각 목록의 재생목록 ID는 지정된 채널의 channel resource에서 가져올 수 있습니다.

그런 다음 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 썸네일 이미지는 일반적으로 120x90픽셀이고 channel 리소스의 default 썸네일 이미지는 일반적으로 88x88픽셀입니다.
  • 동일한 유형의 리소스라도 원본 이미지 또는 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 채널의 워터마크 이미지를 삭제합니다.