Cómo usar la API de descarga e información de YouTube

Necesitas obtener programáticamente un enlace descargable para un video específico de YouTube o un formato de audio y enviarlo esta semana. Al final de este artículo, realizarás una solicitud autenticada para recuperar una tarea de descarga lista para usar (con un enlace de progreso y una miniatura) utilizando la API de descarga e información de YouTube en Zyla API Hub, integrarlo en tu backend o automatización, y invocarlo desde un agente de IA a través de MCP.

Lo que esta API te ofrece

La API de descarga e información de YouTube expone un único endpoint enfocado que inicializa un activo descargable para una URL de YouTube dada en el formato que elijas. Soporta videos regulares de YouTube (no transmisiones en vivo) y devuelve:

• Una bandera de éxito que indica si la solicitud fue aceptada.
• Un id opaco para la descarga solicitada.
• Una URL de imagen (la miniatura del video) que puedes mostrar inmediatamente en tu interfaz de usuario.
• Un progress_url para monitorear el progreso del trabajo fuera de tu aplicación si es necesario.

Los usos comunes incluyen:

• Construir un descargador de medios interno para revisiones de cumplimiento o QA de contenido.
• Agregar funciones de “guardar en la biblioteca” o “clip offline” dentro de tu producto.
• Extraer pistas de audio para transcripción o análisis.

Todo se ejecuta a través de tu cuenta de Zyla y una única clave API. Zyla API Hub proporciona una cuenta, una clave API y un modelo de suscripción para todas las APIs en el mercado. Puedes explorar más de 10,000 APIs públicas en zylalabs.com e integrar múltiples servicios detrás de la misma clave.

Comenzando en Zyla API Hub

Para comenzar:

1. Abre la lista de la API en Zyla: Comienza prueba de 7 días en la API de descarga e información de YouTube.
2. Haz clic en Suscribirse o Comenzar prueba gratuita (cuando esté disponible) y obtén tu clave API.
3. Usa esa clave en el encabezado de autorización en cada solicitud.

La facturación es por suscripción + cuota (no pago por llamada). Para el primer uso, esta API ofrece una prueba de 7 días en su página de ítem. Consulta la página de la API para las opciones de acceso y precios actuales.

Resumen del endpoint y formatos

La API actualmente proporciona un endpoint de descarga. Proporcionas una URL de video de YouTube y un formato, y responde con un identificador de trabajo, miniatura y un enlace de progreso.

• Método: GET
• URL: https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
• Parámetros:
  • url (string, requerido): la URL completa de visualización de YouTube (ejemplo proporcionado a continuación).
  • format (string, requerido): uno de los formatos de video o audio permitidos a continuación.

Formatos disponibles

Formatos de video:

• 360p
• 480p
• 720p
• 1080p
• 1440p
• 2160p

Formatos de audio:

• mp3
• m4a
• flac
• opus
• wav

Notas que importan en producción:

• Los enlaces de descarga de audio expiran después de 2 horas. Incorpora esto en tu experiencia de usuario para evitar enlaces obsoletos.
• Este endpoint solo soporta la descarga de videos regulares (no transmisiones en vivo).

Solicitud cURL que puedes copiar y ejecutar

A continuación se muestra la solicitud oficial, que puedes copiar y pegar, utilizando una URL de YouTube y un formato de video de 720p. Reemplaza YOUR_API_KEY con tu clave de Zyla:

curl -s -X GET "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DaGSKrC7dGcY&format=720" \
-H "Authorization: Bearer YOUR_API_KEY"

Ejemplos de respuestas JSON

Este es el ejemplo de respuesta oficial. Incluye una bandera de éxito, un id estable para esta solicitud, una URL de imagen para la miniatura del video y un URL de progreso que puedes usar para verificar el estado del trabajo:

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

La misma estructura que deberías esperar para otras solicitudes válidas (los valores diferirán en tiempo de ejecución):

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

Usa este esquema para conectar tu lógica de análisis. Por ejemplo, muestra la imagen inmediatamente en tu interfaz de usuario mientras comienza el trabajo de descarga, y persiste el id para vincular la acción de tu usuario al trabajo:

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

Interpretando los campos de respuesta

• success: true significa que la solicitud fue aceptada y se creó un trabajo.
• id: un identificador único para el trabajo resultante. Almacénalo junto a la acción de tu usuario para trazabilidad.
• image: una URL directa a la miniatura del video. Útil para marcadores de posición en la interfaz de usuario y vistas de cola.
• progress_url: un enlace que puedes usar externamente para verificar el progreso del procesamiento. Úsalo para proporcionar actualizaciones de progreso visibles para el usuario o monitoreo interno. Las descargas de audio tienen enlaces sensibles al tiempo (expiran después de 2 horas), así que coordina los flujos de usuario en consecuencia.

Ejemplo en Python: solicitar y analizar

El siguiente fragmento de Python demuestra cómo llamar al endpoint de descarga, validar la respuesta y extraer los campos que realmente usarás en tu aplicación. Coincide con la misma solicitud mostrada en el ejemplo de cURL:

import os
import urllib.parse
import requests

API_KEY = os.environ.get("ZYLA_API_KEY", "YOUR_API_KEY")

BASE_URL = "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download"

def request_download(youtube_url: str, fmt: str):
params = {
"url": youtube_url,
"format": fmt
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# Si tu URL contiene caracteres especiales, codifícalo al construir URLs manuales;
# requests manejará correctamente el diccionario params.
resp = requests.get(BASE_URL, params=params, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
# Comprobaciones mínimas de forma para robustez
if not isinstance(data, dict) or "success" not in data:
raise ValueError("Forma de respuesta inesperada")
if not data.get("success"):
# La API puede devolver success=false para entradas inválidas; maneja esto de manera adecuada.
# Puedes registrar datos para diagnósticos.
raise RuntimeError(f"Solicitud no exitosa: {data}")
# Extrae los campos que tu aplicación usará:
job_id = data.get("id")
thumbnail = data.get("image")
progress_link = data.get("progress_url")
return job_id, thumbnail, progress_link

if __name__ == "__main__":
video_url = "https://www.youtube.com/watch?v=aGSKrC7dGcY"
format_choice = "720" # Usa cualquier formato soportado: 360p, 480p, 720p, 1080p, 1440p, 2160p, mp3, m4a, flac, opus, wav
job_id, thumbnail, progress_link = request_download(video_url, format_choice)
print("Job ID:", job_id)
print("Thumbnail:", thumbnail)
print("Progress URL:", progress_link)

Para referencia, aquí está el JSON oficial que el código espera analizar:

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

Selección de formato y consejos de experiencia del usuario

Al construir tu interfaz de usuario o CLI, presenta solo los formatos que tu flujo de trabajo puede manejar a continuación. Algunas pautas pragmáticas:

• Para vistas previas de video más rápidas, 360p o 480p están bien. Para archivo o edición, 1080p y superiores.
• Para transcripción solo de audio, m4a o wav son opciones comunes. Recuerda: los enlaces de descarga de audio expiran después de 2 horas; realiza la última obtención rápidamente después de recibir la información del trabajo.
• Si el usuario selecciona una resolución muy alta (1440p/2160p), infórmale que el procesamiento y los tamaños de archivo serán más grandes.
• Muestra la imagen inmediatamente desde el campo de imagen para confirmar el video correcto antes de que finalice la descarga.

Preparación operativa: confiabilidad, idempotencia y cuotas

Para enviar esta semana sin sorpresas:

• Vincula el id devuelto a tu propia fila de base de datos que representa la acción del usuario (por ejemplo, una tabla “DownloadRequest”). Eso te da trazabilidad.
• Si encolas múltiples solicitudes para el mismo par video/formato, considera deduplicar por URL de YouTube + formato de tu lado antes de hacer una nueva llamada a la API.
• Maneja respuestas HTTP no 200 registrando el cuerpo de la respuesta y reintentando solo cuando sea apropiado. No hagas bucles de reintentos ciegos.
• Recuerda el modelo de suscripción + cuota en Zyla. Monitorea tu cuota restante desde tu panel de Zyla y considera la presión de retroceso si operas a gran escala.
• Debido a que los enlaces de descarga de audio expiran después de 2 horas, ya sea:
  • Inicia la obtención del archivo final inmediatamente en tu backend después de haber preparado el almacenamiento, o
  • Solicita al usuario que descargue dentro de la ventana de tiempo y proporciona un flujo de actualización de un clic que re-invoque la API si es necesario.

Zyla unifica la autenticación y el acceso a través de APIs, por lo que puedes agregar herramientas relacionadas más tarde sin nuevas claves. Explora más servicios de medios en zylalabs.com.

Patrones de integración en el mundo real

• Cola de revisión interna: Crea un pequeño servicio que acepte una URL de YouTube y un formato objetivo. Al enviarlo, llama al endpoint de descarga, almacena el id y muestra la imagen de inmediato. Un trabajador en segundo plano puede verificar periódicamente el URL de progreso y notificar al revisor cuando el activo esté listo.
• Extracción de audio de podcast: Ofrece mp3 o m4a como opciones. Activa el endpoint de descarga justo después de que el usuario pegue un enlace; una vez que el archivo esté listo en tu flujo posterior, envíalo inmediatamente a tu motor de transcripción. Debido a la ventana de enlace de audio de 2 horas, encadena estos pasos de cerca.
• Módulo offline en un LMS: Para un curso con lecciones de YouTube incrustadas, solicita previamente versiones de 480p o 720p. Almacena los ids de trabajo y muestra las miniaturas de imagen en la lista de lecciones mientras las descargas se completan en segundo plano.

Llamando a la API desde un agente de IA a través de MCP

Si usas un cliente compatible con MCP (por ejemplo, Claude Code, Cursor, Windsurf), puedes permitir que el agente llame a las APIs de Zyla a través de la puerta de enlace MCP. Proporciona tu clave API de Zyla en el endpoint de MCP e instruye al agente para que realice un GET autenticado a la URL del Hub:

• Endpoint MCP: MCP
• Pasa tu clave API como: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
• Haz que el agente invoque:
  • GET https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
  • Parámetros de consulta: url, format
  • Encabezado: Authorization: Bearer YOUR_API_KEY

En lenguaje natural, puedes decirle a tu agente: “Llama al endpoint de descarga de la API de descarga e información de YouTube con esta URL de YouTube y formato 720, incluye Authorization: Bearer, y devuelve el id, la imagen y el progress_url.” La misma estructura que el ejemplo oficial se aplica. Usa el id devuelto para etiquetar los pasos subsiguientes en el flujo de trabajo de tu agente.

Lista de verificación de solución de problemas y validación

• Errores de autenticación: Asegúrate de que el encabezado de autorización sea exactamente “Bearer YOUR_API_KEY” con una clave válida de tu panel de Zyla.
• Entrada incorrecta: Verifica que la url sea una URL completa de visualización de YouTube. Asegúrate de que el formato sea uno de los valores listados y esté correctamente codificado si se concatena a una URL.
• Enlaces de audio sensibles al tiempo: Si un usuario intenta obtener un objeto de audio después de 2 horas, vuelve a ejecutar la solicitud y comienza la descarga rápidamente.
• Tipos de contenido no soportados: Este endpoint maneja solo videos regulares. Si la fuente es una transmisión en vivo, informa al usuario y desautoriza la acción.
• Confiabilidad de la red: Agrega un retroceso simple y registra los cuerpos para respuestas no 2xx para acelerar la depuración.

Consideraciones de seguridad

• Almacena tu clave API de Zyla en tu gestor de secretos o variables de entorno; nunca la codifiques directamente en el código del lado del cliente.
• Desinfecta y valida las URLs de YouTube enviadas por el usuario antes de enviarlas a la API.
• Nunca envíes tu clave API a frontends no confiables. Prefiere llamadas del lado del servidor o herramientas del lado del agente en entornos confiables.

Referencia: solicitud y respuesta oficiales

Para conveniencia, aquí están los bloques oficiales nuevamente para copiar/pegar rápidamente.

Solicitud

curl -s -X GET "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DaGSKrC7dGcY&format=720" \
-H "Authorization: Bearer YOUR_API_KEY"

Respuesta

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

Preguntas frecuentes

¿Qué formatos puedo solicitar?
Video: 360p, 480p, 720p, 1080p, 1440p, 2160p. Audio: mp3, m4a, flac, opus, wav.

¿Cómo me autentico?
Incluye el encabezado Authorization: Bearer YOUR_API_KEY en cada solicitud. Obtén tu clave en la lista de la API de Zyla después de suscribirte.

¿Los enlaces de audio expiran?
Sí. Los enlaces de descarga de audio expiran después de 2 horas. Comienza tu descarga final rápidamente o re-invoca la API si es necesario.

¿Se admiten transmisiones en vivo?
No. El endpoint solo admite la descarga de videos regulares.

¿Cómo empiezo una prueba?
Usa la página del ítem en Zyla para comenzar tu prueba de 7 días: Comienza prueba de 7 días en la API de descarga e información de YouTube.

Envíalo

Puedes integrar la API de descarga e información de YouTube en menos de una hora: llama al endpoint de descarga con url y format, lee id/image/progress_url, y conecta una tarea de fondo corta para finalizar tu flujo de trabajo. Crea tu cuenta en Zyla y comienza la prueba de 7 días desde la lista para obtener tu clave API y salir en vivo esta semana.