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. Этот метод представляет собой первые два шага трехэтапного процесса обновления изображения баннера для канала:

  1. Вызовите channelBanners.insert , чтобы загрузить данные двоичного изображения на YouTube. Изображение должно иметь соотношение сторон 16:9 и размер не менее 2048x1152 пикселей. Мы рекомендуем загружать изображение размером 2560х1440 пикселей.
  2. Извлеките значение свойства url из ответа, который API возвращает на шаге 1.
  3. Вызовите метод 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 Изменяет список воспроизведения. Например, вы можете изменить название, описание или статус конфиденциальности плейлиста.

Результат поиска содержит информацию о видео, канале или плейлисте 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 x 90 пикселей, а миниатюра изображения default для ресурса channel обычно имеет размер 88 x 88 пикселей.
  • Ресурсы одного и того же типа могут по-прежнему иметь разные размеры миниатюр для определенных изображений в зависимости от разрешения исходного изображения или контента, загруженного на YouTube. Например, видео высокой четкости может поддерживать миниатюры более высокого разрешения, чем видео не 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 Удаляет изображение водяного знака канала.