Necesitas una forma confiable de convertir una URL de video de redes sociales en un archivo descargable esta semana. Al final de esta guía, llamarás a una API para solicitar un video en el formato y resolución elegidos, luego consultarás una segunda API para recuperar la URL de descarga directa—lista para guardar en almacenamiento, adjuntar a un CMS, o pasar a un trabajador en segundo plano.
Qué hace esta API y cuándo usarla
La API de Descarga de Video de la API de Redes Sociales te permite enviar una URL de video de plataformas como Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter y Twitch, elegir un formato/calidad objetivo, y luego recuperar el enlace descargable una vez que se complete el procesamiento. Soporta resoluciones y formatos de audio populares incluyendo 144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg y webm. Los casos de uso típicos incluyen:
- Ingesta automatizada de URLs enviadas por creadores en tu pipeline de medios
- Pre-generación de activos en una resolución específica para una aplicación móvil
- Creación de extractos solo de audio para flujos de trabajo de podcast o transcripción
- Construcción de herramientas internas para archivar y categorizar clips sociales
En Zyla API Hub, cada API utiliza el mismo modelo de suscripción y cuota bajo una sola cuenta y clave. Eso significa que puedes integrar esta API ahora y luego agregar otros puntos finales de medios o sociales sin incorporar un nuevo proveedor. Zyla alberga más de 10,000 APIs públicas en diversas categorías, pero esta guía se centra en descargas de medios.
Comenzando en Zyla API Hub
Para implementar esta integración rápidamente:
- Abre la lista de la API: Iniciar prueba de 7 días en la API de Descarga de Video de Redes Sociales.
- Haz clic en Suscribirse o inicia la prueba de 7 días (o 50 solicitudes—verifica la lista para lo que se ofrece actualmente).
- Copia tu clave API. La autenticación es un solo encabezado: Authorization: Bearer YOUR_API_KEY.
La facturación es por suscripción + cuota, no por llamada. No hay Plan Gratuito. Para las opciones de acceso y precios actuales, consulta la página de la API anterior. Si deseas explorar más integraciones de medios y sociales más adelante, visita Zyla API Hub.
Descripción general del endpoint
Esta API ofrece un flujo de dos pasos:
- Solicita un video en el formato y calidad deseados a través de Download, que devuelve un ID para tu trabajo.
- Después de esperar ~30 segundos, consulta Get Video Download URL usando el ID devuelto para recuperar el enlace descargable final.
1) Download (enviar un video para procesamiento)
- Método: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20671/download
- Descripción: Descargar videos en cualquier formato y calidad. También funciona con Youtube Shorts.
- Formatos soportados: 144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg, webm
- Sitios web soportados: Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter, Twitch
- Parámetros de consulta requeridos:
- download (string): la URL del video fuente (por ejemplo, un enlace de Youtube)
- format (string): formato o resolución objetivo (por ejemplo, 720)
Ejemplo oficial de cURL:
curl -s -X GET "https://zylalabs.com/api/10960/social-media-api-video-download/20671/download?download=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D4iuPJ1pdNkY&format=720" \
-H "Authorization: Bearer YOUR_API_KEY"Respuesta JSON oficial:
{
"success": true,
"id": "v2_stream_72b78f7ca6c4f1f267cb",
"title": "Team Feature: Algeria | The Rise of \
"e;Mazadona,\" Algeria’s Secret World Cup Weapon",
"thumbnail": "https://i.ytimg.com/vi/4iuPJ1pdNkY/hqdefault.jpg",
"format": "mp4 [720p]"
}Lo que importa para tu integración:
- success: boolean que indica que la solicitud fue aceptada.
- id: el identificador de procesamiento que usarás en el siguiente endpoint. Persiste este valor.
- title, thumbnail, format: útiles para registro, UX o nombrado de archivos.
2) Get Video Download URL (consultar el enlace final)
- Método: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20672/get-video-download-url
- Descripción: Recuperar la URL descargable usando el ID del paso Download.
- Importante: Después de obtener el ID del endpoint anterior, debes esperar 30 segundos antes de usarlo aquí. El procesamiento generalmente toma de 30 segundos a 1 minuto y puede variar con la carga de la cola.
- Parámetros de consulta requeridos:
- getVideo (string): el ID devuelto por Download, por ejemplo, v2_stream_72b78f7ca6c4f1f267cb
Ejemplo oficial de cURL:
Respuesta JSON oficial:
Lo que importa para tu integración:
- status: verifica que sea "completed" antes de intentar usar la URL.
- progress: un indicador de progreso entero; útil para retroceso de consulta y UX.
- downloads: un array; usa el objeto con tipo "primary". Su url es el enlace de descarga directa.
De extremo a extremo: solicitar, esperar, obtener URL
El endpoint Download activa el procesamiento y devuelve un id. Debes esperar al menos 30 segundos antes de llamar a Get Video Download URL. Muchos equipos implementan un bucle de consulta simple con retroceso o una espera fija y un pequeño número de reintentos, dependiendo de los tiempos de cola en tu carga de trabajo.
Ejemplo en Python
El siguiente ejemplo realiza ambos pasos. Este:
- Envía un GET a Download con la URL del video y el formato elegido
- Espera 30 segundos
- Llama a Get Video Download URL con el id devuelto
- Imprime la URL descargable final cuando esté disponible
import time
import urllib.parse
import requests
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1) Solicitar procesamiento para un video y formato específicos
video_url = "https://www.youtube.com/watch?v=4iuPJ1pdNkY"
format_value = "720"
download_endpoint = (
"https://zylalabs.com/api/10960/social-media-api-video-download/20671/download"
)
params = {
"download": video_url,
"format": format_value,
}
resp = requests.get(download_endpoint, headers=HEADERS, params=params, timeout=60)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError(f"La solicitud de descarga falló: {data}")
job_id = data.get("id")
title = data.get("title")
fmt = data.get("format")
print(f"Solicitado: {title} ({fmt}), id de trabajo: {job_id}")
# 2) Esperar al menos 30 segundos antes de obtener la URL de descarga
time.sleep(30)
poll_endpoint = (
"https://zylalabs.com/api/10960/social-media-api-video-download/20672/get-video-download-url"
)
poll_params = {"getVideo": job_id}
poll_resp = requests.get(poll_endpoint, headers=HEADERS, params=poll_params, timeout=60)
poll_resp.raise_for_status()
poll_data = poll_resp.json()
status = poll_data.get("status")
progress = poll_data.get("progress")
print(f"Estado: {status}, progreso: {progress}")
downloads = poll_data.get("downloads") or []
primary = next((d for d in downloads if d.get("type") == "primary"), None)
if primary and primary.get("url"):
print(f"URL de descarga: {primary['url']}")
else:
print("Aún no hay URL de descarga. Intenta consultar nuevamente después de un breve retraso.")Notas prácticas de integración
- Cadencia de consulta: La API indica que debes esperar 30 segundos después de recibir el id. Si necesitas robustez, espera de 30 a 45 segundos, luego consulta una vez. Si el estado no es "completed", espera y consulta nuevamente. La respuesta de muestra muestra progreso en 100 cuando está completo.
- Formatos: El parámetro de formato acepta entradas como 720, 1080, 4k para calidad de video y mp3, wav, ogg, webm para opciones de audio o contenedor. Elige según tus objetivos de almacenamiento y reproducción.
- Fuentes soportadas: Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter y Twitch. Si estás construyendo una interfaz de descarga universal, valida el dominio de la URL de entrada antes de enviarla a la API.
- Manejo de metadatos: el título y la miniatura de la respuesta de Download son útiles para vistas previas en tu interfaz mientras el procesamiento está en curso; guárdalos con el id del trabajo.
- Almacenamiento: La respuesta de Get Video Download URL devuelve un enlace directo en downloads[0].url (donde el tipo es "primary"). Guarda el archivo resultante en tu almacenamiento de objetos o pásalo a tu pipeline de medios.
- Manejo de errores: Si success es falso o el estado indica que el trabajo no está listo, evita bucles ajustados. Aplica retroceso exponencial para reducir solicitudes innecesarias.
- Cuotas: El acceso es a través de suscripción + cuota, no por llamada. Verifica tu cuota restante en el panel de Zyla y en la lista de la API; evita sobreconsultar para conservar la cuota.
Flujos de trabajo del mundo real
Carga de creador con normalización de URL
Cuando un creador envía una URL de contenido, tu backend puede:
- Analizar y validar el dominio de la URL (debe ser uno de los sitios soportados).
- Llamar a Download con format=720 para una línea base amigable para móviles.
- Almacenar id, título y miniatura y mostrar un estado de “preparando descarga” al usuario.
- Después de 30 a 60 segundos, consultar Get Video Download URL y persistir la URL final en un estado de “listo” para entrega o procesamiento adicional.
Extractos de audio para transcripción o podcasting
Si solo necesitas audio, establece el formato en mp3, wav o ogg. Luego ejecuta tu servicio de transcripción o adjunta el audio a tu generador de feeds. Esto evita obtener el archivo de video de alta resolución cuando solo necesitas audio.
Ingesta por lotes para curaduría editorial
Para tareas de curaduría semanales, encola URLs de video en una cola de trabajos. Los trabajadores solicitan trabajos de Download primero, luego duermen al menos 30 segundos, y finalmente consultan Get Video Download URL para obtener el enlace final. Persiste el título y la miniatura para vistas previas editoriales.
Llamando a la API desde un agente de IA (MCP)
Si prefieres orquestar llamadas a través de un cliente compatible con MCP (por ejemplo, Claude Code, Cursor, Windsurf), puedes enrutar solicitudes a través del endpoint MCP de Zyla. Proporciona tu clave a través del parámetro de consulta al inicializar la conexión MCP y llama a las mismas URLs de Hub mostradas arriba con el encabezado Authorization.
Documentos y punto de entrada: MCP. Esto permite a los agentes de IA invocar las solicitudes GET exactas que viste anteriormente, usando tu clave API de Zyla para autenticación, dentro del entorno de ejecución de herramientas de tu agente.
Cómo elegir formatos y gestionar tiempos
- Elegir resoluciones: 720 es un fuerte valor predeterminado para web y móvil. Usa 1080 o superior para aplicaciones de smart TV o masters editoriales. Si el ancho de banda es limitado, 360 o 480 reduce el tamaño de transferencia.
- Elegir formatos de audio: mp3 es ampliamente soportado; wav puede ser conveniente para pipelines sin comprimir; ogg se adapta a algunos stacks de código abierto.
- Consideraciones de tiempo: El servicio indica una espera requerida de 30 segundos después de obtener el id. El procesamiento se completa en aproximadamente 30 segundos a 1 minuto dependiendo de la carga de la cola. Diseña tus trabajadores para manejar este retraso de manera adecuada.
Consejos de seguridad y confiabilidad
- Autenticación: Siempre incluye Authorization: Bearer YOUR_API_KEY en cada llamada. Mantén la clave en tu administrador de secretos.
- Manejo de URL: Usa codificación estándar de URL para el parámetro de descarga para evitar la truncación de cadenas de consulta (como en el cURL oficial).
- Reintentos: Las llamadas de red pueden fallar de forma transitoria. Implementa reintentos limitados con retroceso en respuestas 5xx o tiempos de espera, especialmente para el paso de consulta.
- Observabilidad: Registra el id del trabajo, el título y el formato elegido al llamar a Download. Al consultar, registra el estado y el progreso para identificar desaceleraciones y picos de cola.
- Ciclo de vida del almacenamiento: Después de obtener la URL final y almacenar el medio, considera expirar el enlace original en tu sistema y confiar en tu propio almacenamiento para la entrega posterior.
Referencia rápida: parámetros y respuestas
Download
- Método HTTP: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20671/download
- Parámetros requeridos:
- download: URL completa del video (por ejemplo, https://www.youtube.com/watch?v=4iuPJ1pdNkY)
- format: formato o calidad deseada (por ejemplo, 720, 1080, 4k, mp3, wav, ogg, webm)
- Autenticación: Authorization: Bearer YOUR_API_KEY
- Campos de respuesta:
- success: booleano
- id: identificador del trabajo para el siguiente paso
- title: título del video
- thumbnail: URL de la miniatura
- format: descriptor de formato legible por humanos
Get Video Download URL
- Método HTTP: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20672/get-video-download-url
- Parámetros requeridos:
- getVideo: el id del paso Download
- Autenticación: Authorization: Bearer YOUR_API_KEY
- Comportamiento: espera 30 segundos antes de la primera llamada; el procesamiento generalmente toma de 30 a 60 segundos.
- Campos de respuesta:
- success: booleano
- status: por ejemplo, "completed"
- progress: porcentaje entero
- downloads: array de objetos con tipo, url y has_ssl
Resolviendo problemas comunes
- La consulta inmediata no devuelve URL: Asegúrate de haber esperado al menos 30 segundos después de la respuesta de Download. Si aún está incompleto, espera y consulta nuevamente.
- URL no soportada: Verifica que el dominio sea uno de los sitios soportados (Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter, Twitch). Normaliza o valida las URLs antes de enviarlas.
- Formato incorrecto: Usa uno de los formatos soportados exactamente como se indica (por ejemplo, 720, 1080, 4k, mp3, wav, ogg, webm). Evita agregar extensiones de archivo a menos que se especifique en los valores aceptados.
- Cuota excedida: La API es por suscripción + cuota. Monitorea el uso en tu panel de Zyla y actualiza si es necesario.
FAQ
¿Cuánto tiempo debo esperar antes de llamar a Get Video Download URL?
Espera al menos 30 segundos después de recibir el id del endpoint Download. El procesamiento generalmente se completa en 30 segundos a 1 minuto dependiendo de la carga de la cola.
¿Qué sitios están soportados?
Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter y Twitch.
¿Qué formatos puedo solicitar?
144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg, webm.
¿Qué autenticación se requiere?
Usa el encabezado Authorization: Bearer YOUR_API_KEY en cada solicitud.
¿Es esto por llamada?
No. El acceso es por suscripción + cuota. Consulta la página de la API para las opciones de acceso y precios actuales.
Implementalo
Si estás listo para convertir enlaces sociales en medios descargables hoy, comienza con los dos endpoints en esta guía y conéctalos a tu flujo de trabajo o webhook. Crea tu cuenta y obtén una clave aquí: Iniciar prueba de 7 días en la API de Descarga de Video de Redes Sociales. Luego, itera sobre formatos e intervalos de consulta para coincidir con los objetivos de rendimiento de tu aplicación.
