Guia de Integração da API do Facebook Premium Downloader com Python e Zyla API Hub

Você precisa buscar programaticamente os metadados públicos de Reels/vídeos do Facebook e baixar MP4s para um fluxo de trabalho interno esta semana. Ao final deste guia, você terá uma integração Python funcional que inicia um trabalho de download assíncrono, verifica a conclusão e salva o MP4, além de uma maneira rápida de buscar apenas os metadados—usando a API do Facebook Premium Downloader no Zyla API Hub.

O que esta API faz e quando usá-la

A API do Facebook Premium Downloader fornece duas capacidades para Reels e vídeos públicos do Facebook:

Ilustração: Guia de Integração da API do Facebook Premium Downloader com Python e Zyla API Hub

Iniciar um trabalho de download assíncrono que gera um MP4 baixável do CDN do Facebook uma vez concluído.
Buscar informações do vídeo (metadados) sem executar um fluxo de trabalho de download.

Casos de uso típicos incluem ingestão editorial automatizada, filas de curadoria de UGC, arquivamento de conformidade, ou qualquer backend onde você precise do arquivo MP4 ou metadados para um Reel/vídeo público. A API espera URLs públicas do Facebook, como /reel/…, /watch/?v=, /videos/…, ou fb.watch/…

Começando no Zyla API Hub

Abra a listagem da API do Facebook Premium Downloader no Zyla API Hub e se inscreva. O Zyla usa uma conta, uma chave de API e um modelo de assinatura + cota—sem cobrança por chamada. Para esta API, você pode iniciar um teste de 7 dias ou usar 50 requisições para validar sua integração. Não há Plano Gratuito. Verifique a página da API para opções de acesso e preços atuais.

Uma vez inscrito, você receberá uma chave de API. Todas as requisições mostradas abaixo passam a chave como Authorization: Bearer YOUR_API_KEY.

Autenticação e cabeçalhos

Cabeçalho: Authorization: Bearer YOUR_API_KEY
Todos os exemplos abaixo usam os caminhos de URL do Zyla Hub para esta listagem. Não chame hosts de origem diretamente.

Visão geral dos endpoints

1) Informações do Vídeo

Recupere metadados para um Reel/vídeo público do Facebook sem iniciar um trabalho de download.

Método: GET
URL: https://zylalabs.com/api/13612/facebook-premium-downloader-api/30379/video-information
Parâmetros necessários:
- url (string): A URL pública do vídeo do Facebook (exemplo fornecido abaixo)

cURL (pronto para copiar e colar):

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"

Exemplo de resposta 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": "Job started. Poll progress_url every 3–5 seconds until progress is 100, then use download_url."
}

O que você realmente usará:

post_id: O ID do Facebook que você pode armazenar para futuras reconciliações.
title, duration, likes: Contexto leve para UI ou indexação.
image: URL da miniatura para pré-visualizações.
url: Link canônico de origem.

2) Download

Inicie um trabalho de download assíncrono para um Reel/vídeo público do Facebook. A resposta fornece um id de trabalho e um progress_url. Verifique essa URL a cada 3–5 segundos até que o progresso seja 100, então use download_url dessa resposta (o MP4 é servido pelo CDN do Facebook; o Hub não faz proxy de mídia binária).

Método: GET
URL: https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download
Parâmetros necessários:
- url (string): A URL pública do vídeo do Facebook (exemplo fornecido abaixo)
- format (string): mp4

cURL (pronto para copiar e colar):

Exemplo de resposta JSON:

O que você realmente usará:

id: Sua referência de trabalho para logs.
progress_url: Verifique essa URL até que o progresso seja 100; então leia download_url dessa resposta para buscar o MP4.
image: Miniatura conveniente enquanto o trabalho está em execução.

Implementação em Python: iniciar trabalho, verificar e salvar MP4

O trecho abaixo faz o seguinte:

Chama Download para iniciar um trabalho para a URL do Reel fornecida.
Verifica progress_url a cada poucos segundos.
Quando o progresso atinge 100, busca download_url e transmite o MP4 para o 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" e "download_url" quando 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("Download job did not reach 100% in time")

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"Download job failed to start: {job}")
print(f"Job started: id={job.get('id')}")
print(f"Thumbnail: {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 download_url found in progress response: {result}")

output_file = "facebook_reel.mp4"
print(f"Downloading: {mp4_url}")
save_mp4(mp4_url, output_file)
print(f"Saved to {output_file}")

Notas:

Intervalo de verificação: 3–5 segundos conforme a orientação do endpoint. O exemplo usa 4s.
Timeouts: Ajuste max_wait_seconds dependendo do seu orçamento de latência de fila.
Mídia binária: O MP4 real é servido do CDN do Facebook via download_url; não é feito proxy pelo Hub.

Padrões de uso prático

Portão de metadados: Chame Informações do Vídeo primeiro para validar uma URL, extrair post_id e exibir a miniatura na sua UI. Só inicie o Download se o usuário confirmar a ingestão.
Trabalhador de fila: Inicie trabalhos de Download no seu processo web, coloque o progress_url na fila e deixe um trabalhador verificar e persistir o MP4.
Idempotência: Armazene o id do trabalho junto com a URL de origem e seu ID de ativo. Se uma requisição for reexecutada, você pode decidir se reutiliza ou inicia um novo trabalho.
Nomenclatura de arquivos: Combine post_id das Informações do Vídeo com um timestamp para nomes de arquivos determinísticos (por exemplo, 1716864869572990.mp4).
Cache: Se você processar o mesmo Reel várias vezes, evite rebaixar conteúdo inalterado usando seu próprio armazenamento indexado por post_id.

Passo a passo detalhado: fluxo de ponta a ponta

Passo 1 — (Opcional) Buscar metadados do vídeo

Use Informações do Vídeo para verificar rapidamente uma URL pública e apresentar detalhes aos usuários antes de baixar:

Passo 2 — Iniciar o trabalho de download assíncrono

Chame Download com a mesma URL e format=mp4:

Persistir id e progress_url da resposta. O campo de mensagem lembra você de verificar a cada poucos segundos até estar pronto.

Passo 3 — Verificar progress_url e baixar

A cada 3–5 segundos, GET o progress_url fornecido. Quando o progresso atingir 100, leia download_url e transmita o MP4 para o disco ou armazenamento de objetos. O Hub não faz proxy de mídia binária; seu aplicativo baixa diretamente da URL do CDN retornada pelo endpoint de progresso.

Cobrança, cotas e configuração do ambiente

Modelo de cobrança: Assinatura + cota. Não é pago por chamada.
Teste: Sua primeira API pode começar com um teste de 7 dias ou 50 requisições. Sem Plano Gratuito.
Ambiente: Armazene YOUR_API_KEY em seu gerenciador de segredos (ou como ZYLA_API_KEY em desenvolvimento).
Tentativas: Para problemas de rede transitórios no progress_url ou na requisição final do MP4, use backoff exponencial.

Tratamento de erros e casos extremos

Vídeos privados ou indisponíveis: A API tem como alvo Reels/vídeos públicos. Se uma URL não for pública, espere falhas ou dados incompletos.
Orçamento de verificação: Certifique-se de que seu trabalhador respeite os SLAs da fila; aumente max_wait_seconds se suas cargas de trabalho forem grandes ou se o CDN de origem for lento.
Ciclo de vida de armazenamento: Após salvar o MP4, mova-o para armazenamento frio se você esperar reproduções raras; mantenha post_id para evitar re-buscas.

Casos de uso do mundo real

Pipelines de revisão editorial: Enriqueça as submissões mostrando título, duração e miniatura antes do download.
Arquivamento de conformidade: Capture MP4 e metadados para trilhas de auditoria com id do trabalho e post_id registrados para rastreabilidade.
Curadoria de conjuntos de dados: Use Informações do Vídeo para filtrar por duração ou presença de likes antes de gastar cota em downloads.

Chame esta API de agentes de IA via MCP

Se você usar Claude Code, Cursor, Windsurf ou qualquer cliente compatível com MCP, pode direcionar chamadas através do endpoint MCP do Zyla. Forneça sua chave de API do Zyla para o endpoint MCP e deixe o agente orquestrar chamadas com o mesmo fluxo Authorization: Bearer.

Docs: MCP

Lista de verificação de produção

Defina Authorization: Bearer YOUR_API_KEY em cada requisição.
Use apenas URLs públicas do Facebook em formatos suportados (/reel/…, /watch/?v=, /videos/…, fb.watch/…).
Verifique progress_url a cada 3–5 segundos; aguarde o progresso == 100 antes de acessar download_url.
Transmita o MP4 para evitar grandes buffers de memória.
Registre id do trabalho, URL de origem e caminho do arquivo final para observabilidade.

FAQ

A API faz proxy do arquivo MP4?
Não. O Hub inicia o trabalho e retorna um progress_url. Uma vez completo, use download_url da resposta de progresso para baixar o MP4 diretamente do CDN do Facebook.

Posso usar vídeos privados ou não listados do Facebook?
Os endpoints são para Reels/vídeos públicos. Se uma URL não for pública, os metadados e downloads podem falhar.

Qual cabeçalho de autenticação devo enviar?
Authorization: Bearer YOUR_API_KEY em cada requisição para as URLs do Zyla Hub.

Como devo verificar o trabalho?
Verifique progress_url a cada 3–5 segundos. Quando o progresso for 100, leia download_url e salve o arquivo.

Há um plano gratuito?
Não há Plano Gratuito. Sua primeira API pode começar com um teste de 7 dias ou 50 requisições. Verifique a página do item para acesso e preços atuais.

Pronto para implementar? Inicie sua integração e valide de ponta a ponta com um teste na página de listagem: Iniciar teste de 7 dias na API do Facebook Premium Downloader.