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 siguientes secciones, se identifican los diferentes tipos de recursos que puedes recuperar con 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. La clave de API está disponible en el panel Acceso a la API de la Consola para desarrolladores de 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 recupera 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 esta manera: ?access_token=oauth2-token
    • Usa el encabezado Authorization HTTP de esta forma: Authorization: Bearer oauth2-token

    Puedes encontrar instrucciones completas para implementar la autenticación de OAuth 2.0 en tu aplicación 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 en particular realizó en YouTube. Las acciones que se informan en los feeds de actividades incluyen calificar un video, compartir un video, marcar un video 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 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
URIs relativos a 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 canal del usuario.

Subtítulos

Un recurso caption representa una pista de subtítulos de YouTube. Una pista de subtítulos se asocia con exactamente 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
URIs relativos a https://www.googleapis.com/youtube/v3
delete DELETE /captions Borra 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 Devuelve una lista de los segmentos de subtítulos asociados a un video específico. La respuesta de la API no contiene los subtítulos reales y el método captions.download permite recuperar un segmento 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 para la pista o ambas acciones.

ChannelBanners

Un recurso channelBanner contiene la URL que usarías para establecer una imagen recién subida como la 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
URIs relativos a 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 del 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 un tamaño mínimo de 2048 x 1152 píxeles. Te recomendamos que subas una imagen de 2560 px por 1440 px.
  2. Extrae el valor de la propiedad url de la respuesta que devuelve la API para el paso 1.
  3. Llama al método channels.update para actualizar la configuración de desarrollo de la marca del canal. Establece el valor de la propiedad brandingSettings.image.bannerExternalUrl en la URL que obtuviste 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 o populares de un canal, o bien los videos de una o más playlists.

Las secciones de un canal solo se ven si el canal muestra 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 estantes.

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

Método Solicitud HTTP Descripción
URIs relativos a https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Borra una sección del canal.
insert POST /channelSections Agrega una sección del canal al canal del usuario autenticado. Un canal puede crear un máximo de 10 estantes.
list GET /channelSections Devuelve una lista de recursos channelSection que coinciden con los criterios de la solicitud a la API.
update PUT /channelSections Actualiza una sección del 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /channels Devuelve 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. 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 un hilo de comentarios de YouTube, que incluye un comentario de nivel superior y las respuestas a ese comentario, si existen. 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 usar el método comments.list si deseas recuperar todas las respuestas a un comentario en particular. Además, 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /commentThreads Devuelve una lista de subprocesos de comentarios que coinciden con los parámetros de la 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 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /comments Devuelve una lista de comentarios que coinciden con los parámetros de la 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 del video asociado a 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.
delete DELETE /comments Borra un comentario.
update PUT /comments Modifica un comentario.

I18nLanguages

Un recurso i18nLanguage identifica un idioma de la aplicación que admite el sitio web de YouTube. El idioma de la aplicación también se conoce como idioma de la IU. En el caso del sitio web de YouTube, se puede seleccionar automáticamente un idioma de la 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 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 valor del parámetro hl cuando se llaman a métodos de la API, como 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Devuelve una lista de los idiomas de la aplicación que admite 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 configuración regional de contenido. En el caso del sitio web de YouTube, se podría seleccionar automáticamente una región de contenido en función de heurísticas 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 en el 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 valor del parámetro regionCode cuando se llaman 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /i18nRegions Devuelve 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 un canal de YouTube. Un miembro brinda apoyo económico 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 su representación de recursos y la lista de sus propiedades.

Método Solicitud HTTP Descripción
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /members Enumera los miembros (antes conocidos como "patrocinadores") de un canal. La solicitud a la API debe estar autorizada por el propietario del canal.

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 su representación de recursos y la lista de sus propiedades.

Método Solicitud HTTP Descripción
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Devuelve 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 orden 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 la 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 channel resource para 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
URIs relativos a 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. 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, como las 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 están asociadas a un canal, que es una colección de videos, listas de reproducción e información adicional de YouTube de una persona, un grupo o empresa. Puedes recuperar los IDs de las playlists de 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
URIs relativos a 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 búsqueda contiene información acerca de 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 único de identificación, 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /search Devuelve una colección de resultados de la búsqueda que coinciden con los parámetros de la consulta especificados en la solicitud de la API. De forma predeterminada, un conjunto de resultados de la búsqueda identifica los recursos video, channel y playlist coincidentes, pero también puedes configurar las búsquedas para recuperar 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
URIs relativos a 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 los diferentes tamaños de imágenes en miniatura asociados a un recurso. 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étera) hace referencia 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 de un recurso video suele ser de 120 px por 90 px, y la imagen en miniatura default de 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
URIs relativos a 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 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
URIs relativos a https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Recupera 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 con 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
URIs relativos a 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
URIs relativos a 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 contener contenido abusivo.

Marcas de agua

Un recurso watermark identifica una imagen que se muestra durante la reproducción de los videos de un canal especificado. 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
URIs relativos a 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.