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. Las listas a continuación identifican los diferentes tipos de recursos que puedes recuperar mediante el uso de 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 que se informan 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 a ella, 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 se admite.

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 devuelve 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 específico. Ten en cuenta que la respuesta de la API no contiene los subtítulos reales y que el método captions.download proporciona la capacidad de 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 archivo de subtítulos nuevo o realizar ambas acciones.

ChannelBanners

Un recurso channelBanner contiene la URL que usarías para configurar una imagen recién subida como la imagen del 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 imágenes binarias a YouTube. La imagen debe tener una relación de aspecto de 16:9 y tener, al menos, 2,048 × 1,152 píxeles. Te recomendamos subir una imagen de 2560 px por 1440 px.
  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 del desarrollo de la marca del canal. Establece el valor de la propiedad brandingSettings.image.bannerExternalUrl en la URL obtenida en el paso 2.

ChannelSections

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, las cargas más populares o videos de una o más playlists.

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 del 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 borrar la sección de un canal.
insert POST /channelSections Agrega una sección al canal del usuario autenticado. Cada canal puede crear hasta 10 bibliotecas.
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, actualmente, este método solo admite actualizaciones de los objetos brandingSettings y invideoPromotion del recurso channel y sus propiedades secundarias.

CommentThreads

Un recurso commentThread contiene información sobre una conversación de comentarios de YouTube, que incluye 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 recursos comment anidados dentro del recurso commentThread. El recurso commentThread no contiene necesariamente todas las respuestas a un comentario. Debes utilizar el método comments.list si deseas recuperar todas las respuestas para un comentario en particular. Ten en cuenta también 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 Devuelve una lista de subprocesos de comentarios que coinciden con los parámetros de solicitud de la API.
insert POST /commentThreads Crea un comentario de nivel superior nuevo. 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, el comentario puede ser un comentario de nivel superior o una respuesta a un comentario 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 a la API.
setModerationStatus POST /comments/setModerationStatus Establece el estado de moderación de uno o más comentarios. El propietario del canal o video asociado con los comentarios debe autorizar la solicitud a la API.
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 se admite.
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 en función del contenido de un canal y de 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.

I18nLanguages

Un recurso i18nLanguage identifica un lenguaje de aplicación que es compatible con el sitio web de YouTube. El lenguaje de la aplicación también puede denominarse lenguaje de 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 de la IP. Un usuario también puede seleccionar manualmente el idioma de la IU que desee en 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 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 Devuelve una lista de los idiomas de aplicación compatibles con el sitio web de YouTube.

I18nRegions

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 de contenido también se conoce como una configuración regional del contenido. Para el sitio web de YouTube, una región de contenido se puede seleccionar automáticamente según una heurística, como el dominio de YouTube o la ubicación de la IP del usuario. Un usuario también puede seleccionar manualmente la región de 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 regional se puede usar como el valor del parámetro regionCode cuando se llama a métodos de 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 compatibles con el sitio web de YouTube.

Miembros

Un recurso member representa a un miembro de un canal de YouTube. Este 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.

MembershipsLevels

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 son propiedad del canal que autorizó la solicitud a la API. Los niveles se muestran en orden de visualización implícito.

PlaylistItems

Un recurso playlistItem identifica otro recurso, como un video, que se incluye en una playlist. Además, el recurso playlistItem contiene detalles sobre el recurso incluido que se relacionan específicamente con la forma en que se usa ese recurso en esa playlist.

YouTube también usa una playlist para identificar la lista de videos subidos de un canal, y cada playlistItem de esa lista representa un video subido. Puedes recuperar el ID de la playlist de esa lista desde el channel resource de un canal determinado. Luego, puedes usar el método playlistItems.list en 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 playlist 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 playlists para identificar colecciones especiales de videos para un canal, por ejemplo:

  • videos subidos
  • videos con calificación positiva (me gusta)
  • historial de reproducciones
  • Ver más tarde
Para ser más específicos, estas listas están asociadas a un canal, que es una colección de los videos, las playlists y otra información de YouTube de una persona, un grupo o una empresa. Puedes recuperar los ID de playlists 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 playlist 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 dirige 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 imágenes 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.

VideoAbuseReportReasons

Un recurso videoAbuseReportReason contiene información sobre un motivo por el que un video se podría marcar por incluir contenido abusivo. Cuando tu aplicación llama al método videos.reportAbuse para denunciar un video abusivo, la solicitud utiliza 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 Recupera una lista de los motivos que pueden usarse 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 Denunciar 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 Elimina la imagen de marca de agua de un canal.