API Reference

API данных YouTube позволяет включать функции, обычно выполняемые на веб-сайте YouTube, в ваш собственный веб-сайт или приложение. В приведенных ниже списках указаны различные типы ресурсов, которые вы можете получить с помощью API. API также поддерживает методы для вставки, обновления или удаления многих из этих ресурсов.

В этом справочном руководстве объясняется, как использовать API для выполнения всех этих операций. Руководство организовано по типам ресурсов. Ресурс представляет собой тип элемента, который является частью взаимодействия с YouTube, например видео, плейлист или подписка. Для каждого типа ресурсов в руководстве указано одно или несколько представлений данных, а ресурсы представлены в виде объектов JSON. В руководстве также перечислены один или несколько поддерживаемых методов ( LIST , POST , DELETE и т. д.) для каждого типа ресурсов и объясняется, как использовать эти методы в вашем приложении.

Вызов API

К запросам API данных YouTube применяются следующие требования:

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 в вашем приложении можно найти в руководстве по аутентификации .

Типы ресурсов

Activities

Ресурс activity содержит информацию о действии, которое конкретный канал или пользователь предпринял на YouTube. Действия, сообщаемые в каналах активности, включают оценку видео, совместное использование видео, пометку видео как избранное, загрузку видео и т. д. Каждый ресурс activity определяет тип действия, канал, связанный с действием, и ресурс(ы), связанные с действием, например видео, которое было оценено или загружено.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /activities	Возвращает список событий активности канала, соответствующих критериям запроса. Например, вы можете получить события, связанные с определенным каналом или с собственным каналом пользователя.
insert	POST /activities	Примечание. Этот метод устарел и больше не поддерживается.

Captions

Ресурс caption представляет собой дорожку субтитров YouTube. Дорожка субтитров связана ровно с одним видео YouTube.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
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-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
insert	POST /channelBanners/insert	Загружает изображение баннера канала на YouTube. Этот метод представляет собой первые два шага в трехэтапном процессе обновления изображения баннера для канала: Вызовите метод channelBanners.insert , чтобы загрузить данные двоичного изображения на YouTube. Изображение должно иметь соотношение сторон 16:9 и иметь размер не менее 2048x1152 пикселей. Мы рекомендуем загружать изображение размером 2560 на 1440 пикселей. Извлеките значение свойства url из ответа, возвращаемого API для шага 1. Вызовите метод channels.update , чтобы обновить настройки фирменного стиля канала. Задайте для свойства brandingSettings.image.bannerExternalUrl URL-адрес, полученный на шаге 2.

ChannelSections

Ресурс channelSection содержит информацию о наборе видео, которые канал выбрал для показа. Например, в разделе могут быть представлены последние загрузки канала, самые популярные загрузки или видео из одного или нескольких плейлистов.

Обратите внимание, что разделы канала видны только в том случае, если канал отображает содержимое в режиме просмотра (а не в режиме просмотра ленты). Чтобы разрешить каналу отображать содержимое в представлении просмотра, задайте для свойства brandingSettings.channel.showBrowseView значение true для указанного канала.

Канал может создать максимум 10 полок.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
delete	DELETE /channelSections	Удаляет раздел канала.
insert	POST /channelSections	Добавляет раздел канала в канал аутентифицированного пользователя. Канал может создать максимум 10 полок.
list	GET /channelSections	Возвращает список ресурсов channelSection , соответствующих критериям запроса API.
update	PUT /channelSections	Обновляет раздел канала.

Channels

Ресурс channel содержит информацию о канале YouTube.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /channels	Возвращает коллекцию из нуля или более ресурсов channel , которые соответствуют критериям запроса.
update	PUT /channels	Обновляет метаданные канала. Обратите внимание, что в настоящее время этот метод поддерживает только обновления объектов brandingSettings и invideoPromotion ресурса channel и их дочерних свойств.

CommentThreads

Ресурс commentThread содержит информацию о ветке комментариев YouTube, которая содержит комментарий верхнего уровня и ответы на этот комментарий, если таковые существуют. Ресурс commentThread может представлять комментарии либо к видео, либо к каналу.

И комментарий верхнего уровня, и ответы на самом деле являются ресурсами comment , вложенными в ресурс commentThread . Ресурс commentThread не обязательно содержит все ответы на комментарий, и вам нужно использовать метод comments.list , если вы хотите получить все ответы для определенного комментария. Также обратите внимание, что на некоторые комментарии нет ответов.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /commentThreads	Возвращает список веток комментариев, соответствующих параметрам запроса API.
insert	POST /commentThreads	Создает новый комментарий верхнего уровня. Чтобы добавить ответ на существующий комментарий, используйте метод comments.insert .

Comments

Ресурс comment содержит информацию об одном комментарии YouTube. Ресурс comment может представлять собой комментарий к видео или каналу. Кроме того, комментарий может быть комментарием верхнего уровня или ответом на комментарий верхнего уровня.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
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-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /guideCategories	Возвращает список категорий, которые можно связать с каналами YouTube.

I18nLanguages

Ресурс i18nLanguage определяет язык приложения, поддерживаемый веб-сайтом YouTube. Язык приложения также можно назвать языком пользовательского интерфейса. Для веб-сайта YouTube язык приложения может выбираться автоматически на основе настроек учетной записи Google, языка браузера или IP-адреса. Пользователь также может вручную выбрать нужный язык пользовательского интерфейса в нижнем колонтитуле сайта YouTube.

Каждый ресурс i18nLanguage идентифицирует код языка и имя. Код языка можно использовать в качестве значения параметра hl при вызове таких методов API, как videoCategories.list и guideCategories.list .

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /i18nLanguages	Возвращает список языков приложений, поддерживаемых веб-сайтом YouTube.

I18nRegions

Ресурс i18nRegion определяет географическую область, которую пользователь YouTube может выбрать в качестве предпочтительного региона контента. Область контента также может называться локалью контента. Для веб-сайта YouTube область контента может выбираться автоматически на основе эвристики, такой как домен YouTube или IP-местоположение пользователя. Пользователь также может вручную выбрать желаемую область контента в нижнем колонтитуле сайта YouTube.

Каждый ресурс i18nRegion идентифицирует код региона и имя. Код региона можно использовать в качестве значения параметра regionCode при вызове таких методов API, как search.list , videos.list , activities.list и videoCategories.list .

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /i18nRegions	Возвращает список регионов контента, поддерживаемых веб-сайтом YouTube.

Members

Ресурс member представляет участника канала для канала YouTube. Участник оказывает регулярную денежную поддержку создателю и получает особые преимущества. Например, участники могут общаться в чате, когда создатель включает для чата режим только для участников.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /members	Список участников (ранее известных как «спонсоры») канала. Запрос API должен быть авторизован владельцем канала.

MembershipsLevels

Ресурс membershipsLevel определяет уровень цен для создателя, авторизовавшего запрос API.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /membershipsLevels	Возвращает коллекцию из нуля или более ресурсов membershipsLevel , принадлежащих каналу, авторизовавшему запрос API. Уровни возвращаются в неявном порядке отображения.

PlaylistItems

Ресурс playlistItem идентифицирует другой ресурс, например видео, которое включено в список воспроизведения. Кроме того, ресурс playlistItem содержит сведения о включенном ресурсе, которые конкретно относятся к тому, как этот ресурс используется в этом списке воспроизведения.

YouTube также использует список воспроизведения для идентификации списка загруженных видео канала, где каждый playlistItem в этом списке представляет одно загруженное видео. Вы можете получить идентификатор списка воспроизведения для этого списка из channel resource для данного канала. Затем вы можете использовать метод playlistItems.list для списка.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
delete	DELETE /playlistItems	Удаляет элемент плейлиста.
insert	POST /playlistItems	Добавляет ресурс в список воспроизведения.
list	GET /playlistItems	Возвращает коллекцию элементов плейлиста, соответствующих параметрам запроса API. Вы можете получить все элементы списка воспроизведения в указанном списке воспроизведения или получить один или несколько элементов списка воспроизведения по их уникальным идентификаторам.
update	PUT /playlistItems	Изменяет элемент списка воспроизведения. Например, вы можете обновить позицию элемента в списке воспроизведения.

Playlists

Ресурс playlist представляет собой список воспроизведения YouTube. Плейлист — это набор видео, которые можно просматривать последовательно и делиться ими с другими пользователями. Список воспроизведения может содержать до 200 видео, и YouTube не ограничивает количество списков воспроизведения, которые создает каждый пользователь. По умолчанию списки воспроизведения общедоступны для других пользователей, но списки воспроизведения могут быть общедоступными или частными.

YouTube также использует плейлисты для определения специальных коллекций видео для канала, таких как:

• загруженные видео
• видео с положительной оценкой (понравилось)
• смотреть историю
• посмотреть позже

Чтобы быть более конкретным, эти списки связаны с каналом, который представляет собой набор видео, плейлистов и другой информации YouTube о человеке, группе или компании. Вы можете получить идентификаторы списков воспроизведения для каждого из этих списков из channel resource для данного канала.

Затем вы можете использовать метод playlistItems.list для получения любого из этих списков. Вы также можете добавлять или удалять элементы из этих списков, вызывая методы playlistItems.insert и playlistItems.delete .

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
delete	DELETE /playlists	Удаляет плейлист.
list	GET /playlists	Возвращает коллекцию списков воспроизведения, соответствующих параметрам запроса API. Например, вы можете получить все списки воспроизведения, принадлежащие прошедшему проверку пользователю, или вы можете получить один или несколько списков воспроизведения по их уникальным идентификаторам.
insert	POST /playlists	Создает плейлист.
update	PUT /playlists	Изменяет список воспроизведения. Например, вы можете изменить название, описание или статус конфиденциальности плейлиста.

Search

Результат поиска содержит информацию о видео, канале или плейлисте YouTube, которые соответствуют параметрам поиска, указанным в запросе API. Хотя результат поиска указывает на уникально идентифицируемый ресурс, такой как видео, у него нет собственных постоянных данных.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /search	Возвращает набор результатов поиска, соответствующих параметрам запроса, указанным в запросе API. По умолчанию набор результатов поиска идентифицирует совпадающие ресурсы video , channel и playlist , но вы также можете настроить запросы для извлечения только определенного типа ресурсов.

Subscriptions

Ресурс subscription содержит информацию о подписке пользователя YouTube. Подписка уведомляет пользователя, когда на канал добавляются новые видео или когда другой пользователь выполняет одно из нескольких действий на YouTube, например загружает видео, оценивает видео или комментирует видео.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
delete	DELETE /subscriptions	Удаляет подписку.
insert	POST /subscriptions	Добавляет подписку на канал аутентифицированного пользователя.
list	GET /subscriptions	Возвращает ресурсы подписки, соответствующие критериям запроса API.

Thumbnails

Ресурс- thumbnail идентифицирует различные размеры миниатюрных изображений, связанных с ресурсом. Обратите внимание на следующие характеристики миниатюрных изображений:

• Свойство ресурса snippet.thumbnails — это объект, который идентифицирует эскизы изображений, доступные для этого ресурса.
• Ресурс thumbnail содержит ряд объектов. Имя каждого объекта ( default , medium , high и т. д.) относится к размеру эскиза изображения.
• Различные типы ресурсов могут поддерживать различные размеры эскизов изображений.
• Различные типы ресурсов могут определять разные размеры эскизов изображений с одним и тем же именем. Например, миниатюра default для video обычно имеет размер 120 на 90 пикселей, а миниатюра default для ресурса channel обычно имеет размер 88 на 88 пикселей.
• Ресурсы одного типа могут по-прежнему иметь разные размеры эскизов для определенных изображений в зависимости от разрешения исходного изображения или контента, загруженного на YouTube. Например, HD-видео может поддерживать миниатюры с более высоким разрешением, чем не-HD-видео.
• Каждый объект, содержащий информацию о размере эскиза, имеет свойства width и свойства height . Однако свойства ширины и высоты могут не возвращаться для этого изображения.
• Если загруженное миниатюрное изображение не соответствует требуемым размерам, размер изображения изменяется в соответствии с правильным размером без изменения соотношения сторон. Изображение не обрезается, но может содержать черные полосы, чтобы размер был правильным.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
set	POST /thumbnails/set	Загружает пользовательскую миниатюру видео на YouTube и устанавливает ее для видео.

VideoAbuseReportReasons

Ресурс videoAbuseReportReason содержит информацию о причине, по которой видео будет помечено как содержащее оскорбительный контент. Когда ваше приложение вызывает метод videos.reportAbuse , чтобы сообщить об оскорбительном видео, запрос использует информацию из ресурса videoAbuseReportReason , чтобы определить причину сообщения о видео.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /videoAbuseReportReasons	Получить список причин, по которым можно сообщить об оскорбительных видео.

VideoCategories

Ресурс videoCategory определяет категорию, которая была или может быть связана с загруженными видео.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
list	GET /videoCategories	Возвращает список категорий, которые можно связать с видео YouTube.

Videos

video представляет собой видео YouTube.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
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	Пожаловаться на видео, содержащее оскорбительный контент.

Watermarks

Ресурс watermark идентифицирует изображение, которое отображается во время воспроизведения видео определенного канала. Вы также можете указать целевой канал, на который будет ссылаться изображение, а также сведения о времени, которые определяют, когда водяной знак появляется во время воспроизведения видео, и продолжительность его видимости.

Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .

Метод	HTTP-запрос	Описание
URI относительно https://www.googleapis.com/youtube/v3
set	POST /watermarks/set	Загружает изображение водяного знака на YouTube и устанавливает его для канала.
unset	POST /watermarks/unset	Удаляет изображение водяного знака канала.