Guía de integración de la API de Facebook Premium Downloader de Python con Zyla API Hub

Necesitas obtener programáticamente los metadatos de Reels/videos públicos de Facebook y descargar MP4 para un flujo de trabajo interno esta semana. Al final de esta guía, tendrás una integración de Python funcional que inicia un trabajo de descarga asíncrono, consulta por la finalización y guarda el MP4, además de una forma rápida de obtener solo metadatos: utilizando la API de Facebook Premium Downloader en Zyla API Hub.

Qué hace esta API y cuándo usarla

La API de Facebook Premium Downloader proporciona dos capacidades para Reels y videos públicos de Facebook:

Ilustración: Guía de integración de la API de Facebook Premium Downloader de Python con Zyla API Hub

Iniciar un trabajo de descarga asíncrono que genera un MP4 descargable desde el CDN de Facebook una vez completado.
Obtener información del video (metadatos) sin ejecutar un flujo de trabajo de descarga.

Los casos de uso típicos incluyen la ingestión editorial automatizada, colas de curación de UGC, archivo de cumplimiento, o cualquier backend donde necesites el archivo MP4 o metadatos para un Reel/video público. La API espera URLs públicas de Facebook como /reel/…, /watch/?v=, /videos/…, o fb.watch/…

Comenzando en Zyla API Hub

Abre la lista de la API de Facebook Premium Downloader en Zyla API Hub y suscríbete. Zyla utiliza una cuenta, una clave API y un modelo de suscripción + cuota: sin facturación por llamada. Para esta API, puedes comenzar una prueba de 7 días o usar 50 solicitudes para validar tu integración. No hay Plan Gratuito. Consulta la página de la API para las opciones de acceso y precios actuales.

Una vez suscrito, recibirás una clave API. Todas las solicitudes que se muestran a continuación pasan la clave como Authorization: Bearer YOUR_API_KEY.

Autenticación y encabezados

Encabezado: Authorization: Bearer YOUR_API_KEY
Todos los ejemplos a continuación utilizan las rutas URL de Zyla Hub para esta lista. No llames a los hosts de origen directamente.

Descripción general de los endpoints

1) Información del video

Recupera metadatos para un Reel/video público de Facebook sin iniciar un trabajo de descarga.

Método: GET
URL: https://zylalabs.com/api/13612/facebook-premium-downloader-api/30379/video-information
Parámetros requeridos:
- url (string): La URL pública del video de Facebook (ejemplo proporcionado a continuación)

cURL (listo para copiar y pegar):

curl -s -X GET "https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download?url=https%3A%2F%2Fwww.facebook.com%2Freel%2F1716864869572990%2F&format=mp4" \
-H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta JSON:

{
"success": true,
"id": "ddbea44c8fee0af86c40da80b9fcebb71b43f2ec",
"image": "https://scontent-phl2-1.xx.fbcdn.net/v/t51.82787-15/783144007_18064358021738741_5417564166543599844_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=a27664&_nc_ohc=K3uWHXdnAsgQ7kNvwGYgRLm&_nc_oc=AdrBUhuPSyDpnRP-zBbXB4TK1V0E2f2mz-aGg6GbrFjlKwZbfFAH6ynNbPHxceeh_rw&_nc_zt=23&_nc_ht=scontent-phl2-1.xx&_nc_gid=XrcbYmbN8ZuG357GCmVnIA&_nc_ss=7a289&oh=00_AQJv9a3kURRiH1Uri6TBWExvljPutu75Ucj18F-X6BhbPg&oe=6AA48A83",
"progress_url": "https://fb-download.zylalabs.com/api/progress?id=ddbea44c8fee0af86c40da80b9fcebb71b43f2ec",
"message": "Trabajo iniciado. Consulta progress_url cada 3–5 segundos hasta que el progreso sea 100, luego usa download_url."
}

Lo que realmente usarás:

post_id: El ID de Facebook que puedes almacenar para futuras conciliaciones.
title, duration, likes: Contexto ligero para UI o indexación.
image: URL de la miniatura para vistas previas.
url: Enlace fuente canónico.

2) Descargar

Inicia un trabajo de descarga asíncrono para un Reel/video público de Facebook. La respuesta proporciona un id de trabajo y un progress_url. Consulta esa URL cada 3–5 segundos hasta que el progreso sea 100, luego usa download_url de esa respuesta (el MP4 es servido por el CDN de Facebook; el Hub no hace proxy de medios binarios).

Método: GET
URL: https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download
Parámetros requeridos:
- url (string): La URL pública del video de Facebook (ejemplo proporcionado a continuación)
- format (string): mp4

cURL (listo para copiar y pegar):

Ejemplo de respuesta JSON:

Lo que realmente usarás:

id: Tu referencia de trabajo para registros.
progress_url: Consulta esta URL hasta que el progreso sea 100; luego lee download_url de esa respuesta para obtener el MP4.
image: Miniatura conveniente mientras se ejecuta el trabajo.

Implementación en Python: iniciar trabajo, consultar y guardar MP4

El fragmento a continuación hace lo siguiente:

Llama a Download para iniciar un trabajo para la URL del Reel proporcionada.
Consulta progress_url cada pocos segundos.
Cuando el progreso alcanza 100, obtiene download_url y transmite el MP4 al disco.

import os
import time
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
VIDEO_URL = "https://www.facebook.com/reel/1716864869572990/"

def start_download_job(video_url: str) -> dict:
hub_url = "https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download"
params = {
"url": video_url,
"format": "mp4"
}
resp = requests.get(hub_url, headers={"Authorization": f"Bearer {API_KEY}"}, params=params, timeout=30)
resp.raise_for_status()
return resp.json()

def poll_progress(progress_url: str, interval_seconds: int = 4, max_wait_seconds: int = 180) -> dict:
deadline = time.time() + max_wait_seconds
last = None
while time.time() < deadline:
r = requests.get(progress_url, timeout=30)
r.raise_for_status()
data = r.json()
# Espera campos como "progress" y "download_url" cuando esté completo.
progress = data.get("progress")
if progress is not None:
print(f"progress={progress}")
last = data
if isinstance(progress, int) and progress >= 100:
return data
time.sleep(interval_seconds)
raise TimeoutError("El trabajo de descarga no alcanzó el 100% a tiempo")

def save_mp4(download_url: str, out_path: str):
with requests.get(download_url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(out_path, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)

if __name__ == "__main__":
job = start_download_job(VIDEO_URL)
if not job.get("success"):
raise RuntimeError(f"El trabajo de descarga falló al iniciar: {job}")
print(f"Trabajo iniciado: id={job.get('id')}")
print(f"Miniatura: {job.get('image')}")
progress_url = job["progress_url"]

result = poll_progress(progress_url)
mp4_url = result.get("download_url")
if not mp4_url:
raise RuntimeError(f"No se encontró download_url en la respuesta de progreso: {result}")

output_file = "facebook_reel.mp4"
print(f"Descargando: {mp4_url}")
save_mp4(mp4_url, output_file)
print(f"Guardado en {output_file}")

Notas:

Intervalo de consulta: 3–5 segundos según la guía del endpoint. El ejemplo utiliza 4s.
Timeouts: Ajusta max_wait_seconds dependiendo de tu presupuesto de latencia de cola.
Medios binarios: El MP4 real se sirve desde el CDN de Facebook a través de download_url; no es proxy por el Hub.

Patrones de uso práctico

Puerta de metadatos: Llama a Información del Video primero para validar una URL, extraer post_id y mostrar la miniatura en tu UI. Solo inicia la descarga si el usuario confirma la ingestión.
Trabajador de cola: Inicia trabajos de descarga en tu proceso web, encola el progress_url y deja que un trabajador consulte y persista el MP4.
Idempotencia: Almacena el id del trabajo junto con la URL de origen y tu ID de activo. Si se reintenta una solicitud, puedes decidir si reutilizar o iniciar un nuevo trabajo.
Nomenclatura de archivos: Combina post_id de Información del Video con una marca de tiempo para nombres de archivos deterministas (por ejemplo, 1716864869572990.mp4).
Cacheo: Si procesas el mismo Reel varias veces, omite volver a descargar contenido sin cambios utilizando tu propio almacén indexado por post_id.

Recorrido detallado: flujo de extremo a extremo

Paso 1 — (Opcional) Obtener metadatos del video

Utiliza Información del Video para verificar rápidamente una URL pública y presentar detalles a los usuarios antes de descargar:

Paso 2 — Iniciar el trabajo de descarga asíncrono

Llama a Descargar con la misma URL y format=mp4:

Persiste id y progress_url de la respuesta. El campo de mensaje te recuerda consultar cada pocos segundos hasta que esté listo.

Paso 3 — Consultar progress_url y descargar

Cada 3–5 segundos, GET el progress_url proporcionado. Cuando el progreso alcance 100, lee download_url y transmite el MP4 al disco o almacenamiento de objetos. El Hub no hace proxy de medios binarios; tu aplicación descarga directamente desde la URL del CDN devuelta por el endpoint de progreso.

Facturación, cuotas y configuración del entorno

Modelo de facturación: Suscripción + cuota. No pago por llamada.
Prueba: Tu primera API puede comenzar con una prueba de 7 días o 50 solicitudes. No hay Plan Gratuito.
Entorno: Almacena YOUR_API_KEY en tu gestor de secretos (o como ZYLA_API_KEY en desarrollo).
Reintentos: Para problemas de red transitorios en progress_url o la solicitud final de MP4, utiliza retroceso exponencial.

Manejo de errores y casos límite

Videos privados o no disponibles: La API está dirigida a Reels/videos públicos. Si una URL no es pública, espera fallas o datos incompletos.
Presupuesto de consulta: Asegúrate de que tu trabajador respete los SLA de la cola; aumenta max_wait_seconds si tus cargas de trabajo son grandes o el CDN de origen es lento.
Ciclo de vida del almacenamiento: Después de guardar el MP4, muévelo a almacenamiento en frío si esperas repeticiones raras; conserva post_id para evitar volver a obtenerlo.

Casos de uso en el mundo real

Pipelines de revisión editorial: Enriquece las presentaciones mostrando título, duración y miniatura antes de la descarga.
Archivo de cumplimiento: Captura MP4 y metadatos para auditorías con id de trabajo y post_id registrados para trazabilidad.
Curación de conjuntos de datos: Usa Información del Video para filtrar por duración o presencia de likes antes de gastar cuota en descargas.

Llama a esta API desde agentes de IA a través de MCP

Si usas Claude Code, Cursor, Windsurf, o cualquier cliente compatible con MCP, puedes enrutar llamadas a través del endpoint MCP de Zyla. Proporciona tu clave API de Zyla al endpoint MCP y deja que el agente orqueste llamadas con el mismo flujo Authorization: Bearer.

Docs: MCP

Lista de verificación de producción

Establece Authorization: Bearer YOUR_API_KEY en cada solicitud.
Usa solo URLs públicas de Facebook en formatos soportados (/reel/…, /watch/?v=, /videos/…, fb.watch/…).
Consulta progress_url cada 3–5 segundos; espera a que el progreso sea 100 antes de acceder a download_url.
Transmite y descarga el MP4 para evitar grandes buffers de memoria.
Registra el id del trabajo, la URL de origen y la ruta del archivo final para observabilidad.

FAQ

¿La API hace proxy del archivo MP4?
No. El Hub inicia el trabajo y devuelve un progress_url. Una vez completado, usa download_url de la respuesta de progreso para descargar el MP4 directamente desde el CDN de Facebook.

¿Puedo usar videos privados o no listados de Facebook?
Los endpoints son para Reels/videos públicos. Si una URL no es pública, los metadatos y las descargas pueden fallar.

¿Qué encabezado de autenticación debo enviar?
Authorization: Bearer YOUR_API_KEY en cada solicitud a las URLs de Zyla Hub.

¿Cómo debo consultar el trabajo?
Consulta progress_url cada 3–5 segundos. Cuando el progreso sea 100, lee download_url y guarda el archivo.

¿Hay un plan gratuito?
No hay Plan Gratuito. Tu primera API puede comenzar con una prueba de 7 días o 50 solicitudes. Consulta la página del artículo para el acceso y precios actuales.

¿Listo para implementar? Comienza tu integración y valida de extremo a extremo con una prueba en la página de listado: Inicia prueba de 7 días en la API de Facebook Premium Downloader.