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 listas, 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. 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 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 realizó un canal o usuario en particular en YouTube. Las acciones que se registran en los feeds de actividades incluyen calificar un video, compartirlo, marcarlo como favorito, subirlo, etcétera. Cada recurso activity identifica el tipo de acción, el canal asociado con la acción y los recursos asociados con 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
URIs 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 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 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 relacionados con 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 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 Devuelve 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 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, subir un archivo de subtítulos nuevo o ambas opciones.

ChannelBanners

Un recurso channelBanner contiene la URL que usarías para establecer 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
URIs 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 un tamaño mínimo de 2048 x 1152 píxeles. Te recomendamos que subas una imagen de 2560 × 1440 px.
  2. Extrae el valor de la propiedad url de la respuesta que muestra 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ó para mostrar. Por ejemplo, una sección podría mostrar las cargas más recientes o más populares de un canal, o bien videos de una o más playlists.

Ten en cuenta que las secciones de un canal solo son visibles 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 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
URIs relacionados con https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Borra una sección del canal.
insert POST /channelSections Agrega una sección de canal al canal del usuario autenticado. Un canal puede crear un máximo de 10 bibliotecas.
list GET /channelSections Muestra una lista de recursos channelSection que coinciden con los criterios de solicitud de 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 relacionados con 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. 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 las hay. 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 contiene necesariamente todas las respuestas a un comentario, y debes usar 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
URIs relacionados con https://www.googleapis.com/youtube/v3
list GET /commentThreads Muestra una lista de conversaciones de comentarios que coinciden con los parámetros de solicitud de la API.
insert POST /commentThreads Crea un nuevo comentario 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, 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 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. El propietario del canal o el 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 forma algorítmica en función del contenido de un canal o de otros indicadores, como su popularidad. La lista es similar a las categorías de videos, con la diferencia de que el usuario que sube un video puede asignarle una categoría, pero solo YouTube puede asignar una categoría al 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
URIs 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 idioma de aplicación que admite el sitio web de YouTube. El idioma de la aplicación también se puede denominar idioma de la IU. En el 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 IP. Un usuario también puede seleccionar manualmente el idioma de la IU deseado 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 llaman 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
URIs relacionados con https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Muestra 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 del contenido también se puede denominar configuración regional del 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 IP del usuario. Los usuarios también pueden seleccionar manualmente la región de contenido deseada desde 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 el 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 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 de un canal de YouTube. Un miembro proporciona asistencia monetaria 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 propiedades.

Método Solicitud HTTP Descripción
URIs 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 su representación de recursos y la lista de propiedades.

Método Solicitud HTTP Descripción
URIs 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 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 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
URIs 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. 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 las playlists para identificar colecciones especiales de videos de un canal, como las siguientes:

  • videos subidos
  • videos con calificación positiva (me gusta)
  • historial de reproducciones
  • Ver más tarde
En particular, estas listas están asociadas con un canal, que es una colección de videos, playlists y otra información de YouTube de una persona, un grupo o una empresa. Puedes recuperar los IDs de las playlists de cada una de estas listas desde el channel resource de 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 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 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 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 a 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 consultas para que solo recuperen 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 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 de miniaturas 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 de 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 de 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 de miniatura default para un recurso video suele ser de 120 px por 90 px, y la imagen de 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 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 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 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 relacionados con 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 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
URIs 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 ofensivo

Marcas de agua

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