Como Usar a API de Download e Informações do YouTube

Você precisa buscar programaticamente um link para download de um vídeo específico do YouTube ou formato de áudio e enviá-lo esta semana. Ao final deste artigo, você fará uma solicitação autenticada para recuperar uma tarefa de download pronta para uso (com um link de progresso e miniatura) usando a API de Download e Informações do YouTube no Zyla API Hub, conectá-la ao seu backend ou automação, e invocá-la a partir de um agente de IA via MCP.

O que esta API oferece

A API de Download e Informações do YouTube expõe um único endpoint focado que inicializa um ativo para download para uma URL do YouTube dada em seu formato escolhido. Ela suporta vídeos regulares do YouTube (não transmissões ao vivo) e retorna:

• Uma flag de sucesso indicando se a solicitação foi aceita.
• Um id opaco para o download solicitado.
• Uma URL de imagem (a miniatura do vídeo) que você pode exibir imediatamente em sua interface.
• Um progress_url para monitorar o progresso do trabalho fora do seu aplicativo, se necessário.

Usos comuns incluem:

• Construir um downloader de mídia interno para revisões de conformidade ou QA de conteúdo.
• Adicionar recursos de “salvar na biblioteca” ou “clipe offline” dentro do seu produto.
• Extrair faixas de áudio para transcrição ou pipelines de análise.

Tudo passa pela sua conta Zyla e uma única chave de API. O Zyla API Hub fornece uma conta, uma chave de API e um modelo de assinatura para todas as APIs do mercado. Você pode navegar por mais de 10.000 APIs públicas em zylalabs.com e integrar vários serviços por trás da mesma chave.

Começando no Zyla API Hub

Para começar:

1. Abra a listagem da API no Zyla: Inicie um teste de 7 dias na API de Download e Informações do YouTube.
2. Clique em Inscrever-se ou Iniciar Teste Gratuito (quando disponível) e obtenha sua chave de API.
3. Use essa chave no cabeçalho de Autorização em cada solicitação.

A cobrança é por assinatura + cota (não por chamada). Para uso pela primeira vez, esta API oferece um teste de 7 dias em sua página de item. Verifique a página da API para opções de acesso e preços atuais.

Visão geral do endpoint e formatos

A API atualmente fornece um endpoint de Download. Você fornece uma URL de vídeo do YouTube e um formato, e ela responde com um identificador de trabalho, miniatura e um link de progresso.

• Método: GET
• URL: https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
• Parâmetros:
  • url (string, obrigatório): a URL completa de visualização do YouTube (exemplo fornecido abaixo).
  • format (string, obrigatório): um dos formatos de vídeo ou áudio permitidos abaixo.

Formatos disponíveis

Formatos de vídeo:

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

Formatos de áudio:

• mp3
• m4a
• flac
• opus
• wav

Notas que importam na produção:

• Links de download de áudio expiram após 2 horas. Incorpore isso em sua experiência do usuário para evitar links obsoletos.
• Este endpoint suporta apenas o download de vídeos regulares (não transmissões ao vivo).

Solicitação cURL que você pode copiar e executar

Abaixo está a solicitação oficial, copiável e colável, usando uma URL do YouTube e um formato de vídeo 720p. Substitua YOUR_API_KEY pela sua chave do 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"

Respostas JSON de exemplo

Este é o exemplo de resposta oficial. Ele inclui uma flag de sucesso, um id estável para esta solicitação, uma URL de imagem para a miniatura do vídeo e um URL de progresso que você pode usar para verificar o status do trabalho:

{
"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"
}

A mesma estrutura que você deve esperar para outras solicitações válidas (os valores diferirão em tempo de execução):

{
"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"
}

Use este esquema para conectar sua lógica de análise. Por exemplo, mostre a imagem imediatamente em sua interface enquanto o trabalho de download começa e persista o id para vincular a ação do seu usuário ao trabalho:

{
"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 os campos da resposta

• success: true significa que a solicitação foi aceita e um trabalho foi criado.
• id: um identificador único para o trabalho resultante. Armazene-o junto com a ação do seu usuário para rastreabilidade.
• image: uma URL direta para a miniatura do vídeo. Útil para espaços reservados da interface e visualizações de fila.
• progress_url: um link que você pode usar externamente para verificar o progresso do processamento. Use-o para fornecer atualizações de progresso voltadas para o usuário ou monitoramento interno. Downloads de áudio têm links sensíveis ao tempo (expiram após 2 horas), então coordene os fluxos de usuários de acordo.

Exemplo em Python: solicitar e analisar

O seguinte trecho de Python demonstra como chamar o endpoint de Download, validar a resposta e extrair os campos que você realmente usará em seu aplicativo. Ele corresponde à mesma solicitação mostrada no exemplo 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}"
}
# Se sua URL contiver caracteres especiais, use urlencode ao construir URLs manuais;
# requests lidará corretamente com o dicionário params.
resp = requests.get(BASE_URL, params=params, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
# Verificações mínimas de forma para robustez
if not isinstance(data, dict) or "success" not in data:
raise ValueError("Formato de resposta inesperado")
if not data.get("success"):
# A API pode retornar success=false para entradas inválidas; trate isso de forma adequada.
# Você pode registrar dados para diagnósticos.
raise RuntimeError(f"Solicitação não bem-sucedida: {data}")
# Extraia os campos que seu aplicativo 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" # Use qualquer formato suportado: 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 referência, aqui está o JSON oficial que o código espera analisar:

{
"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"
}

Seleção de formato e dicas de experiência do usuário

Ao construir sua interface ou CLI, apresente apenas os formatos que seu fluxo de trabalho pode lidar a montante. Algumas diretrizes pragmáticas:

• Para pré-visualizações de vídeo mais rápidas, 360p ou 480p são adequados. Para arquivamento ou edição, 1080p e acima.
• Para transcrição apenas de áudio, m4a ou wav são escolhas comuns. Lembre-se: links de download de áudio expiram após 2 horas—faça a busca final prontamente após receber as informações do trabalho.
• Se o usuário selecionar uma resolução muito alta (1440p/2160p), informe-o que o processamento e os tamanhos dos arquivos serão maiores.
• Exiba a imagem imediatamente do campo de imagem para confirmar o vídeo correto antes que o download termine.

Prontidão operacional: confiabilidade, idempotência e cotas

Para enviar esta semana sem surpresas:

• Vincule o id retornado à sua própria linha de banco de dados representando a ação do usuário (por exemplo, uma tabela “DownloadRequest”). Isso lhe dá rastreabilidade.
• Se você enfileirar várias solicitações para o mesmo par vídeo/formato, considere desduplicar pela URL do YouTube + formato do seu lado antes de fazer uma nova chamada à API.
• Trate respostas HTTP não-200 registrando o corpo da resposta e tentando novamente apenas quando apropriado. Não faça tentativas cegas.
• Lembre-se do modelo de assinatura + cota no Zyla. Monitore sua cota restante no seu painel do Zyla e considere pressão de retorno se você operar em grande escala.
• Como os links de download de áudio expiram após 2 horas, ou:
  • Inicie a busca do arquivo final imediatamente em seu backend após preparar o armazenamento, ou
  • Solicite ao usuário que faça o download dentro da janela de tempo e forneça um fluxo de atualização com um clique que re-invoque a API, se necessário.

A Zyla unifica autenticação e acesso entre APIs, para que você possa adicionar ferramentas relacionadas mais tarde sem novas chaves. Explore mais serviços de mídia em zylalabs.com.

Padrões de integração do mundo real

• Fila de revisão interna: Crie um pequeno serviço que aceite uma URL do YouTube e um formato alvo. Ao enviar, chame o endpoint de Download, armazene o id e mostre a imagem imediatamente. Um trabalhador em segundo plano pode verificar periodicamente o URL de progresso e notificar o revisor quando o ativo estiver pronto.
• Extração de áudio de podcast: Ofereça mp3 ou m4a como opções. Acione o endpoint de Download logo após o usuário colar um link; uma vez que o arquivo esteja pronto em seu fluxo a montante, envie-o imediatamente para seu mecanismo de transcrição. Devido à janela de 2 horas do link de áudio, encadeie esses passos de perto.
• Módulo offline em um LMS: Para um curso com lições do YouTube incorporadas, pré-solicite versões 480p ou 720p. Armazene ids de trabalho e exiba as miniaturas das imagens na lista de lições enquanto os downloads são concluídos em segundo plano.

Chamando a API de um agente de IA via MCP

Se você usar um cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf), você pode permitir que o agente chame as APIs do Zyla através do gateway MCP. Forneça sua chave de API do Zyla no endpoint MCP e instrua o agente a realizar um GET autenticado na URL do Hub:

• Endpoint MCP: MCP
• Passe sua chave de API como: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
• Faça o agente invocar:
  • GET https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
  • Parâmetros de consulta: url, format
  • Cabeçalho: Authorization: Bearer YOUR_API_KEY

Em linguagem natural, você pode dizer ao seu agente: “Chame o endpoint de download da API de Download e Informações do YouTube com esta URL do YouTube e formato 720, inclua Authorization: Bearer, e retorne o id, imagem e progress_url.” A mesma estrutura do exemplo oficial se aplica. Use o id retornado para marcar etapas subsequentes no fluxo de trabalho do seu agente.

Lista de verificação de solução de problemas e validação

• Erros de autenticação: Certifique-se de que o cabeçalho de Autorização é exatamente “Bearer YOUR_API_KEY” com uma chave válida do seu painel do Zyla.
• Entrada inválida: Verifique se a url é uma URL completa de visualização do YouTube. Certifique-se de que o formato é um dos valores listados e devidamente codificado se concatenado a uma URL.
• Links de áudio sensíveis ao tempo: Se um usuário tentar buscar um objeto de áudio após 2 horas, re-execute a solicitação e inicie o download prontamente.
• Tipos de conteúdo não suportados: Este endpoint lida apenas com vídeos regulares. Se a fonte for uma transmissão ao vivo, informe o usuário e desautorize a ação.
• Confiabilidade da rede: Adicione um simples backoff e registre corpos para respostas não-2xx para acelerar a depuração.

Considerações de segurança

• Armazene sua chave de API do Zyla em seu gerenciador de segredos ou variáveis de ambiente; nunca a codifique diretamente no código do lado do cliente.
• Sanitize e valide URLs do YouTube enviadas pelo usuário antes de enviá-las para a API.
• Nunca faça proxy da sua chave de API para frontends não confiáveis. Prefira chamadas do lado do servidor ou ferramentas do lado do agente em ambientes confiáveis.

Referência: solicitação e resposta oficiais

Para conveniência, aqui estão os blocos oficiais novamente para cópia/colagem rápida.

Solicitação

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"

Resposta

{
"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"
}

FAQ

Quais formatos posso solicitar?
Vídeo: 360p, 480p, 720p, 1080p, 1440p, 2160p. Áudio: mp3, m4a, flac, opus, wav.

Como faço para autenticar?
Inclua o cabeçalho Authorization: Bearer YOUR_API_KEY em cada solicitação. Obtenha sua chave na listagem da API do Zyla após se inscrever.

Os links de áudio expiram?
Sim. Links de download de áudio expiram após 2 horas. Inicie seu download final prontamente ou re-invoque a API se necessário.

As transmissões ao vivo são suportadas?
Não. O endpoint suporta apenas o download de vídeos regulares.

Como inicio um teste?
Use a página do item no Zyla para iniciar seu teste de 7 dias: Inicie um teste de 7 dias na API de Download e Informações do YouTube.

Envie isso

Você pode integrar a API de Download e Informações do YouTube em menos de uma hora: chame o endpoint de Download com url e format, leia id/imagem/progress_url, e conecte uma tarefa de fundo curta para finalizar seu fluxo de trabalho. Crie sua conta no Zyla e inicie o teste de 7 dias a partir da listagem para obter sua chave de API e ficar ativo esta semana.