API Reference

La API de datos de YouTube te permite incorporar funciones que normalmente se ejecutan en el sitio web de YouTube en tu propio sitio web o aplicación. En las listas siguientes se identifican los diferentes tipos de recursos que puedes recuperar usando la API. La API también admite métodos para insertar, actualizar o borrar muchos de estos recursos.

Esta guía de referencia explica cómo utilizar la API para realizar todas estas operaciones. La guía está organizada por tipo de recurso. Un recurso representa un tipo de elemento que comprende parte de la experiencia de YouTube, tal como un video, una lista de reproducción o una suscripción. Para cada tipo de recurso, la guía enumera una o más representaciones de datos, y los recursos se representan como objetos JSON. La guía también incluye uno o más métodos admitidos (LIST, POST, DELETE, etc.) para cada tipo de recurso y se explica cómo utilizar estos métodos en la aplicación.

Llama a la API

Los siguientes requisitos se aplican a las solicitudes de la API de datos de YouTube:

  1. Cada solicitud debe especificar una clave de API (con el parámetro key) o proporcionar un token de OAuth 2.0. Tu clave de API está disponible en el panel Acceso a la API de Developer Console para tu proyecto.

  2. Debes enviar un token de autorización para cada solicitud de inserción, actualización y eliminación. También debes enviar un token de autorización para cualquier solicitud que recupere los datos privados del usuario autenticado.

    Además, algunos métodos de la API para la recuperación de recursos pueden ser compatibles con los parámetros que requieren autorización o pueden contener metadatos adicionales cuando se autorizan las solicitudes. Por ejemplo, una solicitud para recuperar los videos subidos de un usuario también puede contener videos privados si ese usuario específico autoriza la solicitud.

  3. La API es compatible con el protocolo de autenticación OAuth 2.0. Puedes proporcionar un token de OAuth 2.0 de cualquiera de las siguientes maneras:

    • Usa el parámetro de consulta access_token de la siguiente manera: ?access_token=oauth2-token
    • Usa el encabezado HTTP Authorization de la siguiente manera: Authorization: Bearer oauth2-token

    Las instrucciones completas para implementar la autenticación OAuth 2.0 en tu aplicación se pueden encontrar en la guía de autenticación.

Tipos de recursos

Actividades

Un recurso activity contiene información sobre una acción que un canal o usuario específico realizó en YouTube. Las acciones informadas en los feeds de actividad incluyen calificar un video, compartirlo, marcarlo como favorito, subir un video, etcétera. Cada recurso activity identifica el tipo de acción, el canal asociado a la acción y los recursos asociados con la acción, como el video que se calificó o subió.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /activities Muestra una lista de eventos de actividad del canal que cumplen con los criterios de la solicitud. Por ejemplo, puedes recuperar eventos asociados con un canal en particular o con el propio canal del usuario.
insert POST /activities Nota: Este método dejó de estar disponible y ya no es compatible.

Subtítulos

Un recurso caption representa una pista de subtítulos de YouTube. Una pista de subtítulos se asocia con un solo video de YouTube.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /captions Elimina la pista de subtítulos especificada.
download GET /captions/id Descarga una pista de subtítulos. La pista de subtítulos se muestra en su formato original, a menos que la solicitud especifique un valor para el parámetro tfmt y en su idioma original, a menos que la solicitud especifique un valor para el parámetro tlang.
insert POST /captions Sube una pista de subtítulos.
list GET /captions Muestra una lista de pistas de subtítulos asociadas con un video especificado. Ten en cuenta que la respuesta de la API no contiene los subtítulos reales y que el método captions.download permite recuperar una pista de subtítulos.
update PUT /captions Actualiza una pista de subtítulos. Cuando actualizas una pista de subtítulos, puedes cambiar el estado de borrador de la pista, subir un nuevo archivo de subtítulos o realizar ambas acciones.

ChannelBanners

Un recurso channelBanner contiene la URL que utilizarías para establecer una imagen recién subida como imagen de banner de un canal.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Carga una imagen de banner de un canal en YouTube. Este método representa los dos primeros pasos de un proceso de tres pasos para actualizar la imagen de banner de un canal:

  1. Llama al método channelBanners.insert para subir los datos de la imagen binaria a YouTube. La imagen debe tener una relación de aspecto de 16:9 y tener al menos 2048 × 1152 píxeles. Te recomendamos subir una imagen de 2560 píxeles por 1440 píxeles.
  2. Extrae el valor de la propiedad url de la respuesta que la API muestra para el paso 1.
  3. Llama al método channels.update para actualizar la configuración de desarrollo de la marca del canal. Configura el valor de la propiedad brandingSettings.image.bannerExternalUrl según la URL obtenida en el paso 2.

Secciones de canal

Un recurso channelSection contiene información sobre un conjunto de videos que un canal eligió destacar. Por ejemplo, una sección podría incluir las cargas más recientes de un canal, los más populares o los videos de una o más listas de reproducción.

Ten en cuenta que las secciones de un canal solo serán visibles si el canal muestra el contenido en una vista de exploración (en lugar de una vista de feed). Para permitir que un canal muestre contenido en una vista de exploración, establece la propiedad brandingSettings.channel.showBrowseView en true para el canal especificado.

Un canal puede crear un máximo de 10 bibliotecas.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Permite eliminar la sección de un canal.
insert POST /channelSections Agrega una sección al canal del usuario autenticado. Cada canal puede crear 10 bibliotecas como máximo.
list GET /channelSections Muestra una lista de recursos channelSection que coinciden con los criterios de solicitud a la API.
update PUT /channelSections Actualiza la sección de un canal.

Canales

Un recurso channel contiene información sobre un canal de YouTube.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /channels Muestra una colección de cero o más recursos channel que coinciden con los criterios de la solicitud.
update PUT /channels Actualiza los metadatos de un canal. Ten en cuenta que, por el momento, este método solo admite actualizaciones de los objetos brandingSettings y invideoPromotion del recurso channel y sus propiedades secundarias.

Conversaciones de comentarios

Un recurso commentThread contiene información sobre una conversación de comentarios de YouTube, que comprende un comentario de nivel superior y las respuestas a ese comentario (si corresponde). Un recurso commentThread puede representar comentarios sobre un video o un canal.

Tanto el comentario de nivel superior como las respuestas son, en realidad, recursos comment anidados dentro del recurso commentThread. El recurso commentThread no necesariamente contiene todas las respuestas a un comentario y debes utilizar el método comments.list si deseas recuperar todas las respuestas de un comentario en particular. Además, ten en cuenta que algunos comentarios no tienen respuestas.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /commentThreads Muestra una lista de subprocesos de comentarios que coinciden con los parámetros de solicitud de la API.
insert POST /commentThreads Crea un comentario nuevo de nivel superior. Para agregar una respuesta a un comentario existente, usa el método comments.insert.

Comentarios

Un recurso comment contiene información sobre un solo comentario de YouTube. Un recurso comment puede representar un comentario sobre un video o un canal. Además, puede ser una respuesta a un comentario de nivel superior o uno de nivel superior.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /comments Muestra una lista de comentarios que coinciden con los parámetros de solicitud de la API.
setModerationStatus POST /comments/setModerationStatus Establece el estado de moderación de uno o más comentarios. La solicitud a la API debe estar autorizada por el propietario del canal o video asociado con los comentarios.
insert POST /comments Crea una respuesta a un comentario existente. Nota: Para crear un comentario de nivel superior, usa el método commentThreads.insert.
markAsSpam POST /comments/markAsSpam Nota: Este método dejó de estar disponible y ya no es compatible.
delete DELETE /comments Borra un comentario.
update PUT /comments Modifica un comentario.

GuideCategories

Un recurso guideCategory identifica una categoría que YouTube asigna de manera algorítmica según el contenido de un canal u otros indicadores, como la popularidad del canal. La lista es similar a las categorías de videos, con la diferencia de que quien sube un video puede asignar una categoría de video, pero solo YouTube puede asignar una categoría de canal.

Para obtener más información sobre este recurso, consulta la representación de los recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /guideCategories Muestra una lista de las categorías que se pueden asociar con canales de YouTube.

Idiomas

Un recurso i18nLanguage identifica un idioma de aplicación compatible con el sitio web de YouTube. El lenguaje de la aplicación también puede denominarse IU. Para el sitio web de YouTube, se puede seleccionar automáticamente un idioma de aplicación según la configuración de la Cuenta de Google, el idioma del navegador o la ubicación IP. El usuario también podría seleccionar manualmente el idioma de IU que desee desde el pie de página del sitio de YouTube.

Cada recurso i18nLanguage identifica un código de idioma y un nombre. El código de idioma se puede usar como el valor del parámetro hl cuando se llama a métodos de la API como videoCategories.list y guideCategories.list.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Muestra una lista de los idiomas de aplicación que admite el sitio web de YouTube.

Regiones 18

Un recurso i18nRegion identifica un área geográfica que un usuario de YouTube puede seleccionar como la región de contenido preferida. La región del contenido también puede denominarse configuración regional del contenido. Para el sitio web de YouTube, se puede seleccionar automáticamente una región de contenido en función de heurística, como el dominio de YouTube o la ubicación IP del usuario. Un usuario también podría seleccionar manualmente la región del contenido deseada del pie de página del sitio de YouTube.

Cada recurso i18nRegion identifica un código de región y un nombre. El código de región se puede usar como el valor del parámetro regionCode cuando se llama a métodos de la API como search.list, videos.list, activities.list y videoCategories.list.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /i18nRegions Muestra una lista de las regiones de contenido que admite el sitio web de YouTube.

Miembros

Un recurso member representa a un miembro del canal de YouTube. Un miembro proporciona apoyo monetario recurrente a un creador y recibe beneficios especiales. Por ejemplo, los miembros pueden chatear cuando el creador activa el modo exclusivo para miembros en un chat.

Para obtener más información sobre este recurso, consulta la representación de los recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /members Muestra una lista de los miembros (antes conocidos como “patrocinadores”) de un canal. El propietario del canal debe autorizar la solicitud a la API.

Niveles de membresía

Un recurso membershipsLevel identifica un nivel de precios para el creador que autorizó la solicitud a la API.

Para obtener más información sobre este recurso, consulta la representación de los recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Muestra una colección de cero o más recursos membershipsLevel que pertenecen al canal que autorizó la solicitud a la API. Los niveles se muestran en un orden de visualización implícito.

PlaylistItems

Un recurso playlistItem identifica otro recurso, como un video, que se incluye en una lista de reproducción. Además, el recurso playlistItem contiene detalles sobre el recurso incluido que se refieren específicamente a la forma en que se usa ese recurso en esa lista de reproducción.

YouTube también usa una lista de reproducción para identificar la lista de videos subidos de un canal, en la que cada playlistItem representa un video subido. Puedes recuperar el ID de lista de reproducción de esa lista desde channel resource para un canal determinado. Luego, puedes usar el método playlistItems.list para la lista.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Elimina un elemento de una lista de reproducción.
insert POST /playlistItems Agrega un recurso a una lista de reproducción .
list GET /playlistItems Muestra una colección de elementos de una lista de reproducción que coinciden con los parámetros de solicitud de la API. Puedes recuperar todos los elementos de una lista de reproducción en una lista de reproducción específica o recuperar uno o más elementos de una lista de reproducción mediante sus ID únicos.
update PUT /playlistItems Modifica un elemento de una lista de reproducción. Por ejemplo, puedes actualizar la posición del elemento en la lista de reproducción.

Playlists

Un recurso playlist representa una lista de reproducción de YouTube. Una lista de reproducción es una colección de videos que se pueden ver de manera sucesiva y compartir con otros usuarios. Una lista de reproducción puede contener hasta 200 videos. YouTube no limita el número de listas de reproducción que puede crear cada usuario. Gracias a una configuración predeterminada, las listas de reproducción son visibles públicamente a otros usuarios; sin embargo, pueden ser públicas o privadas.

YouTube también usa listas de reproducción para identificar colecciones especiales de videos de un canal, como los siguientes:

  • videos subidos
  • videos con calificación positiva (me gusta)
  • historial de reproducciones
  • Ver más tarde
Para ser más específicos, estas listas se asocian a un canal, que es una colección de los videos, las listas de reproducción y otra información de YouTube de una persona, un grupo o una empresa. Puedes recuperar los ID de listas de reproducción para cada una de estas listas desde channel resource para un canal determinado.

Luego, puedes usar el método playlistItems.list para recuperar cualquiera de esas listas. También puedes agregar o quitar elementos de esas listas llamando a los métodos playlistItems.insert y playlistItems.delete.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /playlists Elimina una lista de reproducción.
list GET /playlists Muestra una colección de listas de reproducción que coinciden con los parámetros de solicitud de la API. Por ejemplo, puede recuperar todas las listas de reproducción pertenecientes al usuario autenticado o puede recuperar una o varias listas de reproducción con sus ID únicos.
insert POST /playlists Crea una lista de reproducción.
update PUT /playlists Modifica una lista de reproducción. Por ejemplo, puede cambiar el título, la descripción o el estado de la privacidad.

Un resultado de la búsqueda contiene información sobre un video, un canal o una lista de reproducción de YouTube que coincide con los parámetros de búsqueda especificados en una solicitud de la API. Si bien un resultado de la búsqueda apunta a un recurso identificable de manera inequívoca, como un video, no tiene sus propios datos persistentes.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /search Muestra una colección de resultados de la búsqueda que coinciden con los parámetros de consulta especificados en la solicitud de la API. De forma predeterminada, un conjunto de resultados de búsqueda identifica los recursos video, channel y playlist coincidentes, pero también puedes configurar consultas para que recuperen solo un tipo específico de recurso.

Suscripciones

Un recurso subscription contiene información sobre la suscripción de un usuario de YouTube. Una suscripción notifica al usuario cuando se agregan nuevos videos a un canal o cuando otro usuario realiza una de varias acciones en YouTube, como subir un video, calificar un video o comentar un video.

Para obtener más información sobre este recurso, consulta la representación de los recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Elimina una suscripción.
insert POST /subscriptions Agrega una suscripción al canal del usuario autenticado.
list GET /subscriptions Muestra los recursos de suscripción que coinciden con los criterios de solicitud de la API.

Miniaturas

Un recurso thumbnail identifica diferentes tamaños de imagen en miniatura asociados con un recurso. Ten en cuenta las siguientes características de las imágenes en miniatura:

  • La propiedad snippet.thumbnails de un recurso es un objeto que identifica las imágenes en miniatura disponibles para ese recurso.
  • Un recurso thumbnail contiene una serie de objetos. El nombre de cada objeto (default, medium, high, etc.) se refiere al tamaño de la imagen en miniatura.
  • Los diferentes tipos de recursos pueden soportar diferentes tamaños de imágenes en miniatura.
  • Los diferentes tipos de recursos pueden definir distintos tamaños de imágenes en miniatura con el mismo nombre. Por ejemplo, la imagen en miniatura default para un recurso video suele ser de 120 px por 90 px, y la imagen en miniatura default para un recurso channel suele ser de 88 px por 88 px.
  • Es posible que los recursos del mismo tipo aún tengan tamaños de imágenes en miniatura diferentes para ciertas imágenes en función de la resolución de la imagen original o el contenido subido a YouTube. Por ejemplo, un video de alta definición puede admitir miniaturas de mayor resolución que los videos que no son de alta definición.
  • Cada objeto que contiene información sobre el tamaño de una imagen en miniatura tiene una propiedad width y una propiedad height. Sin embargo, es posible que las propiedades de anchura y altura no se muestren para esa imagen.
  • Si una imagen en miniatura cargada no coincide con las dimensiones requeridas, la imagen cambia de tamaño para que coincida con el tamaño correcto, sin cambiar la proporción. La imagen no se recorta, pero puede incluir barras de color negro para que el tamaño sea el correcto.

Para obtener más información sobre este recurso, consulta la representación de los recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Carga una miniatura de video personalizada a YouTube y la configura para un video.

Motivos para denunciar videosabuso

Un recurso videoAbuseReportReason contiene información sobre un motivo por el que se marcaría un video por incluir contenido abusivo. Cuando tu aplicación llama al método videos.reportAbuse para denunciar un video abusivo, la solicitud usa la información de un recurso videoAbuseReportReason para identificar el motivo por el que se denuncia el video.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Recuperar una lista de los motivos que se pueden usar para denunciar videos abusivos

VideoCategories

Un recurso videoCategory identifica una categoría que se asoció o podría asociarse a videos subidos.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
list GET /videoCategories Muestra una lista de las categorías que se pueden asociar a los videos de YouTube.

Videos

Un recurso video representa un video de YouTube.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
insert POST /videos Sube un video a YouTube y configura opcionalmente sus metadatos.
list GET /videos Muestra una lista de los videos que coinciden con los parámetros de solicitud de la API.
delete DELETE /videos Elimina un video de YouTube.
update PUT /videos Actualiza los metadatos de un video.
rate POST /videos/rate Agrega una calificación "me gusta" o "no me gusta" a un video o elimina la calificación de un video.
getRating GET /videos/getRating Recupera las calificaciones que el usuario autorizado otorgó a una lista de videos específicos.
reportAbuse POST /videos/reportAbuse Denuncia un video por incluir contenido abusivo.

Marcas de agua

Un recurso watermark identifica una imagen que se muestra durante las reproducciones de videos de un canal específico. También puedes especificar un canal de destino al que vinculará la imagen, así como información de sincronización que determina cuándo aparece la marca de agua en las reproducciones de video y el período de tiempo que será visible.

Consulta la representación y la lista de propiedades de este recurso para obtener más información.

Método Solicitud HTTP Descripción
URI relacionados con https://www.googleapis.com/youtube/v3
set POST /watermarks/set Carga una imagen de marca de agua a YouTube y la establece para un canal.
unset POST /watermarks/unset Borra la imagen de marca de agua de un canal.