Você precisa de uma maneira confiável de transformar uma URL de vídeo de mídia social em um arquivo baixável esta semana. Ao final deste guia, você chamará uma API para solicitar um vídeo no formato e resolução escolhidos e, em seguida, consultará uma segunda API para recuperar a URL de download direto—pronta para ser salva em armazenamento, anexada a um CMS ou passada para um trabalhador em segundo plano.
O que esta API faz e quando usá-la
A API de Download de Vídeo da API de Mídia Social permite que você envie uma URL de vídeo de plataformas como Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter e Twitch, escolha um formato/qualidade alvo e, em seguida, recupere o link baixável assim que o processamento for concluído. Ela suporta resoluções populares e formatos de áudio, incluindo 144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg e webm. Casos de uso típicos incluem:
- Ingestão automatizada de URLs enviadas por criadores em seu pipeline de mídia
- Pré-geração de ativos em uma resolução específica para um aplicativo móvel
- Criando extratos apenas de áudio para fluxos de trabalho de podcast ou transcrição
- Construindo ferramentas internas para arquivar e categorizar clipes sociais
No Zyla API Hub, cada API usa o mesmo modelo de assinatura e cota sob uma única conta e chave. Isso significa que você pode integrar esta API agora e depois adicionar outros pontos finais de mídia ou sociais sem precisar integrar um novo provedor. A Zyla hospeda mais de 10.000 APIs públicas em várias categorias, mas este guia se concentra em downloads de mídia.
Começando no Zyla API Hub
Para enviar esta integração rapidamente:
- Abra a listagem da API: Inicie o teste de 7 dias na API de Download de Vídeo da API de Mídia Social.
- Clique em Inscrever-se ou inicie o teste de 7 dias (ou 50 solicitações—verifique a listagem para o que está atualmente disponível).
- Copie sua chave da API. A autenticação é um único cabeçalho: Authorization: Bearer YOUR_API_KEY.
A cobrança é por assinatura + cota, não por chamada. Não há Plano Gratuito. Para opções de acesso e preços atuais, verifique a página da API acima. Se você quiser navegar por mais integrações de mídia e sociais depois, visite Zyla API Hub.
Visão geral do endpoint
Esta API oferece um fluxo de dois passos:
- Solicite um vídeo no formato e qualidade desejados via Download, que retorna um ID para seu trabalho.
- Após esperar ~30 segundos, consulte Get Video Download URL usando o ID retornado para recuperar o link de download final.
1) Download (envie um vídeo para processamento)
- Método: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20671/download
- Descrição: Baixar vídeos em qualquer formato e qualidade. Funciona também com Youtube Shorts.
- Formatos suportados: 144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg, webm
- Sites suportados: Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter, Twitch
- Parâmetros de consulta necessários:
- download (string): a URL do vídeo de origem (por exemplo, um link do Youtube)
- format (string): formato ou resolução alvo (por exemplo, 720)
Exemplo 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"Resposta JSON oficial:
{
"success": true,
"id": "v2_stream_72b78f7ca6c4f1f267cb",
"title": "Team Feature: Algeria | The Rise of \
"e;Mazadona,\"e; Algeria’s Secret World Cup Weapon",
"thumbnail": "https://i.ytimg.com/vi/4iuPJ1pdNkY/hqdefault.jpg",
"format": "mp4 [720p]"
}O que importa para sua integração:
- success: boolean indicando que a solicitação foi aceita.
- id: o identificador de processamento que você usará no próximo endpoint. Persista-o.
- title, thumbnail, format: úteis para registro, UX ou nomeação de arquivos.
2) Get Video Download URL (consulte o link final)
- Método: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20672/get-video-download-url
- Descrição: Recupere a URL baixável usando o ID da etapa de Download.
- Importante: Após obter o ID do endpoint anterior, você deve esperar 30 segundos antes de usá-lo aqui. O processamento geralmente leva de 30 segundos a 1 minuto e pode variar com a carga da fila.
- Parâmetros de consulta necessários:
- getVideo (string): o ID retornado pelo Download, por exemplo, v2_stream_72b78f7ca6c4f1f267cb
Exemplo oficial de cURL:
Resposta JSON oficial:
O que importa para sua integração:
- status: verifique se está "completed" antes de tentar usar a URL.
- progress: um indicador de progresso inteiro; útil para recuo de polling e UX.
- downloads: um array; use o objeto com tipo "primary". Sua url é o link de download direto.
De ponta a ponta: solicitar, esperar, buscar URL
O endpoint Download aciona o processamento e retorna um id. Você deve então esperar pelo menos 30 segundos antes de chamar Get Video Download URL. Muitas equipes implementam um loop de polling simples com recuo ou uma espera fixa e um pequeno número de tentativas, dependendo dos tempos de fila em sua carga de trabalho.
Exemplo em Python
O exemplo abaixo realiza ambas as etapas. Ele:
- Envia um GET para Download com a URL do vídeo e o formato escolhido
- Espera 30 segundos
- Chama Get Video Download URL com o id retornado
- Imprime a URL de download final quando disponível
import time
import urllib.parse
import requests
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1) Solicitar processamento para um vídeo e 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"Download request failed: {data}")
job_id = data.get("id")
title = data.get("title")
fmt = data.get("format")
print(f"Requested: {title} ({fmt}), job id: {job_id}")
# 2) Esperar pelo menos 30 segundos antes de buscar a URL de download
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"Status: {status}, progress: {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"Download URL: {primary['url']}")
else:
print("No download URL yet. Try polling again after a short delay.")Notas práticas de integração
- Cadeia de polling: A API observa que você deve esperar 30 segundos após receber o id. Se você precisar de robustez, espere 30–45 segundos e, em seguida, consulte uma vez. Se o status não for "completed", espere e consulte novamente. A resposta de exemplo mostra progresso em 100 quando completo.
- Formatos: O parâmetro de formato aceita entradas como 720, 1080, 4k para qualidade de vídeo e mp3, wav, ogg, webm para escolhas de áudio ou contêiner. Escolha com base em seus alvos de armazenamento e reprodução.
- Fontes suportadas: Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter e Twitch. Se você estiver construindo uma interface de download universal, valide o domínio da URL de entrada antes de enviá-la para a API.
- Tratamento de metadados: título e miniatura da resposta de Download são úteis para pré-visualizações em sua interface enquanto o processamento está em andamento; armazene-os com o id do trabalho.
- Armazenamento: A resposta de Get Video Download URL retorna um link direto em downloads[0].url (onde o tipo é "primary"). Salve o arquivo resultante em seu armazenamento de objetos ou passe-o para seu pipeline de mídia.
- Tratamento de erros: Se success for falso ou o status indicar que o trabalho não está pronto, evite loops apertados. Aplique recuo exponencial para reduzir solicitações desnecessárias.
- Quotas: O acesso é via assinatura + cota, não por chamada. Verifique sua cota restante no painel da Zyla e na listagem da API; evite sobrecarga de polling para conservar a cota.
Fluxos de trabalho do mundo real
Upload de criador com normalização de URL
Quando um criador envia uma URL de conteúdo, seu backend pode:
- Analisar e validar o domínio da URL (deve ser um dos sites suportados).
- Chamar Download com format=720 para uma linha de base amigável para dispositivos móveis.
- Armazenar id, título e miniatura e mostrar um status de “preparando download” para o usuário.
- Após 30–60 segundos, consulte Get Video Download URL e persista a URL final em um estado “pronto” para entrega ou processamento adicional.
Extratos de áudio para transcrição ou podcasting
Se você só precisa de áudio, defina o formato como mp3, wav ou ogg. Em seguida, execute seu serviço de transcrição ou anexe o áudio ao seu gerador de feed. Isso evita buscar o arquivo de vídeo em resolução total quando você só precisa de áudio.
Ingestão em lote para curadoria editorial
Para tarefas de curadoria semanais, coloque URLs de vídeo em uma fila de trabalho. Os trabalhadores solicitam trabalhos de Download primeiro, depois dormem por pelo menos 30 segundos e, finalmente, consultam Get Video Download URL para buscar o link final. Persista título e miniatura para pré-visualizações editoriais.
Chamando a API de um agente de IA (MCP)
Se você preferir orquestrar chamadas via um cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf), você pode direcionar solicitações através do endpoint MCP da Zyla. Forneça sua chave via o parâmetro de consulta ao inicializar a conexão MCP e chame as mesmas URLs do Hub mostradas acima com o cabeçalho Authorization.
Docs e ponto de entrada: MCP. Isso permite que agentes de IA invoquem as exatas solicitações GET que você viu anteriormente, usando sua chave da API Zyla para autenticação, dentro do ambiente de execução da ferramenta do seu agente.
Como escolher formatos e gerenciar o tempo
- Escolhendo resoluções: 720 é um forte padrão para web e mobile. Use 1080 ou superior para aplicativos de smart TV ou masters editoriais. Se a largura de banda for limitada, 360 ou 480 reduz o tamanho da transferência.
- Escolhendo formatos de áudio: mp3 é amplamente suportado; wav pode ser conveniente para pipelines não comprimidos; ogg se adapta a algumas pilhas de código aberto.
- Considerações de tempo: O serviço observa uma espera necessária de 30 segundos após obter o id. O processamento é concluído em aproximadamente 30 segundos a 1 minuto, dependendo da carga da fila. Projete seus trabalhadores para lidar com esse atraso de forma elegante.
Dicas de segurança e confiabilidade
- Autorização: Sempre inclua Authorization: Bearer YOUR_API_KEY em cada chamada. Mantenha a chave em seu gerenciador de segredos.
- Tratamento de URL: Use codificação de URL padrão para o parâmetro de download para evitar truncamento de strings de consulta (como no cURL oficial).
- Tentativas: Chamadas de rede podem falhar temporariamente. Implemente tentativas limitadas com recuo em respostas 5xx ou timeouts, especialmente para a etapa de polling.
- Observabilidade: Registre o id do trabalho, título e formato escolhido ao chamar Download. Ao consultar, registre status e progresso para identificar lentidões e picos de fila.
- Ciclo de vida do armazenamento: Após obter a URL final e armazenar a mídia, considere expirar o link original em seu sistema e confiar em seu próprio armazenamento para servir a montante.
Referência rápida: parâmetros e respostas
Download
- Método HTTP: GET
- URL: https://zylalabs.com/api/10960/social-media-api-video-download/20671/download
- Parâmetros necessários:
- download: URL completa do vídeo (por exemplo, https://www.youtube.com/watch?v=4iuPJ1pdNkY)
- format: formato ou qualidade desejada (por exemplo, 720, 1080, 4k, mp3, wav, ogg, webm)
- Auth: Authorization: Bearer YOUR_API_KEY
- Campos de resposta:
- success: booleano
- id: identificador do trabalho para o próximo passo
- title: título do vídeo
- thumbnail: URL da miniatura
- format: descritor de formato legível 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 necessários:
- getVideo: o id da etapa de Download
- Auth: Authorization: Bearer YOUR_API_KEY
- Comportamento: espere 30 segundos antes da primeira chamada; o processamento geralmente leva de 30 a 60 segundos.
- Campos de resposta:
- success: booleano
- status: por exemplo, "completed"
- progress: percentual inteiro
- downloads: array de objetos com tipo, url e has_ssl
Resolvendo problemas comuns
- Polling imediato retorna nenhuma URL: Certifique-se de que você esperou pelo menos 30 segundos após a resposta de Download. Se ainda estiver incompleto, espere e consulte novamente.
- URL não suportada: Verifique se o domínio é um dos sites suportados (Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter, Twitch). Normalize ou valide URLs antes de enviar.
- Formato incorreto: Use um dos formatos suportados exatamente como listado (por exemplo, 720, 1080, 4k, mp3, wav, ogg, webm). Evite adicionar extensões de arquivo, a menos que especificado nos valores aceitos.
- Cota excedida: A API é por assinatura + cota. Monitore o uso em seu painel Zyla e faça upgrade se necessário.
FAQ
Quanto tempo devo esperar antes de chamar Get Video Download URL?
Espere pelo menos 30 segundos após receber o id do endpoint Download. O processamento geralmente é concluído em 30 segundos a 1 minuto, dependendo da carga da fila.
Quais sites são suportados?
Youtube, Facebook, Instagram, SoundCloud, TikTok, X/Twitter e Twitch.
Quais formatos posso solicitar?
144, 240, 360, 480, 720, 1080, 1440, 4k, mp3, wav, ogg, webm.
Que autenticação é necessária?
Use o cabeçalho Authorization: Bearer YOUR_API_KEY em cada solicitação.
É por chamada?
Não. O acesso é por assinatura + cota. Verifique a página da API para opções de acesso e preços atuais.
Envie isso
Se você está pronto para transformar links sociais em mídia baixável hoje, comece com os dois endpoints deste guia e conecte-os ao seu fluxo de trabalho ou webhook. Crie sua conta e obtenha uma chave aqui: Inicie o teste de 7 dias na API de Download de Vídeo da API de Mídia Social. Em seguida, itere sobre formatos e intervalos de polling para corresponder às metas de desempenho do seu aplicativo.
