Você precisa permitir que os usuários baixem um vídeo do YouTube ou extraiam áudio em um formato específico e precisa que isso funcione esta semana. Ao final deste guia, você terá uma solicitação copiável que retorna um trabalho de download pronto para uso para uma URL específica do YouTube, além de notas pragmáticas para integrá-lo ao seu fluxo de trabalho de mídia.
O que esta API faz e quando usá-la
A API de Download e Informações do YouTube no Zyla API Hub oferece um endpoint HTTP simples para solicitar uma versão baixável de um vídeo ou áudio do YouTube em um formato alvo. Você passa a URL do YouTube e o formato que deseja; a API retorna um identificador de trabalho, uma URL de imagem em miniatura e uma URL de progresso que você pode usar para monitorar o trabalho.
Casos de uso típicos:
- Permitir que os usuários baixem um vídeo em 720p ou 1080p para uso offline.
- Extrair faixas de áudio (por exemplo, mp3, m4a, flac, opus, wav) para preenchimentos de podcast ou amostragem de narração.
- Ferramentas em lote que padronizam os uploads dos criadores em um conjunto fixo de entregáveis.
O Zyla API Hub hospeda mais de 10.000 APIs públicas em Mídia e outras categorias sob uma conta, uma chave de API e um modelo de assinatura + cota. Esta API faz parte da categoria Mídia e se concentra na recuperação de vídeo/áudio.
Começando no Zyla API Hub
Para chamar esta API, abra a listagem do marketplace e inscreva-se. Você receberá uma chave de API usada em todas as APIs do Zyla, e você se autentica com um cabeçalho Authorization. A primeira API que você escolher pode ser testada normalmente com um teste de 7 dias ou 50 solicitações—verifique a listagem para o que está disponível agora.
- Vá para a listagem: Iniciar teste de 7 dias na API de Download e Informações do YouTube
- Clique em Inscrever-se (ou Iniciar Teste Gratuito quando disponível) e copie sua chave de API.
- Use o cabeçalho Authorization: Bearer YOUR_API_KEY em suas solicitações.
Você pode explorar outras APIs de Mídia e categorias no Zyla API Hub com a mesma conta e chave.
Endpoint: Download
Este endpoint solicita uma versão baixável da URL do YouTube fornecida em um formato especificado e retorna um descritor de trabalho para acompanhar o progresso.
- Método: GET
- URL: https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
- Parâmetros de consulta obrigatórios:
- url (string): A URL do YouTube. Exemplo: https://www.youtube.com/watch?v=aGSKrC7dGcY (codifique a URL na solicitação).
- format (string): O formato de saída desejado.
Formatos suportados:
- Vídeo: 360p, 480p, 720p, 1080p, 1440p, 2160p
- Áudio: mp3, m4a, flac, opus, wav
Notas:
- Os links de download de áudio expiram após 2 horas.
- Este endpoint suporta o download apenas de vídeos regulares.
Exemplo oficial de cURL
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"Exemplo de resposta oficial
{
"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"
}Significados dos campos que você realmente usará:
- success: Se o trabalho foi enfileirado com sucesso.
- id: O identificador do trabalho; armazene-o para correlacionar logs e estado da UI.
- image: Uma miniatura que você pode mostrar em sua UI enquanto o trabalho está em execução.
- progress_url: Uma URL que você pode consultar para verificar o progresso do trabalho. Use-a para acionar polling em seu frontend ou trabalhador. Se você expuser downloads de áudio, lembre-se da nota sobre os links de áudio expirando após 2 horas uma vez gerados.
Exemplo em Python usando requests
Este exemplo chama o mesmo endpoint com os mesmos parâmetros que o cURL oficial, analisa o JSON e imprime os metadados do trabalho. Mantenha o cabeçalho Authorization e a URL exatamente como mostrado ao testar esse ID de vídeo; troque o formato para um dos valores suportados conforme necessário.
import requests
from urllib.parse import quote_plus
API_KEY = "YOUR_API_KEY"
youtube_url = "https://www.youtube.com/watch?v=aGSKrC7dGcY"
format_value = "720" # ou "1080p", "mp3", "m4a", "flac", "opus", "wav", etc.
encoded_url = quote_plus(youtube_url)
endpoint = (
"https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download"
f"?url={{encoded_url}}&format={{format_value}}"
)
headers = {
"Authorization": f"Bearer {{API_KEY}}",
}
resp = requests.get(endpoint, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
# Use os campos exatamente como retornados pela API
print("Success:", data.get("success"))
print("Job ID:", data.get("id"))
print("Thumbnail:", data.get("image"))
print("Progress URL:", data.get("progress_url"))
# Exemplo: se você quiser fazer polling na progress_url, mantenha um backoff curto e pare
# quando sua UI ou trabalhador vê que o trabalho está completo. O formato das respostas de progresso
# não está documentado aqui; projete seu polling de forma conservadora.Detalhes de implementação que economizam tempo
- Codificação de URL: Sempre codifique a URL do link do YouTube para o parâmetro url. Muitas falhas vêm de e comercial em URLs de visualização.
- Strings de formato: Para vídeos, use as resoluções listadas (por exemplo, 720p ou 1080p). Para áudios, use um dos mp3, m4a, flac, opus, wav. Se sua UI tiver um dropdown, valide contra essa lista antes de chamar.
- Rastreamento de trabalho: Persista o id retornado em seu banco de dados e associe-o ao usuário/sessão atual para que você possa restaurar os indicadores de progresso após uma atualização de página.
- Miniaturas: Use o campo de imagem para fornecer feedback imediato em sua UI enquanto o trabalho de download está em execução.
- Expiração de áudio: Os links de download de áudio expiram após 2 horas uma vez gerados. Se seu fluxo de trabalho envolver recuperação atrasada (por exemplo, e-mail mais tarde), acione a regeneração sob demanda ou instrua os usuários a baixar prontamente.
- Tentativas: Se você implementar polling na progress_url, mantenha seu backoff modesto para evitar sobrecarga. Armazene o estado mais recente em seu armazenamento para evitar flicker na UI.
- Transmissões ao vivo: O endpoint suporta vídeos regulares. Se os usuários colarem transmissões ao vivo, mostre um erro de validação antes de chamar a API.
- Assinatura + cota: Chamadas consomem a cota do seu plano sob sua assinatura; esta API não é paga por chamada. Verifique a listagem para opções de acesso atuais. A primeira API que você escolher normalmente oferece um teste de 7 dias ou 50 solicitações.
Fluxos comuns do mundo real
1) Modal “Baixar como” em um aplicativo web
- O usuário cola uma URL do YouTube e escolhe um formato (por exemplo, vídeo 1080p ou áudio mp3).
- Seu frontend chama seu backend, que invoca o endpoint de Download com url e format.
- Exiba a miniatura da imagem e mostre um indicador de carregamento enquanto você faz polling na progress_url no servidor.
- Quando completo, apresente o link de download final ao usuário. Para áudio, mostre uma nota sobre a expiração de 2 horas.
2) Normalização da biblioteca de mídia em lote
- Mantenha uma fila de URLs do YouTube e formatos alvo (por exemplo, todos os vídeos em 720p para prévias).
- Chame o endpoint de Download para cada trabalho; armazene id e progress_url.
- Tenha um trabalhador que faça polling na progress_url para avançar os estados dos trabalhos e postar resultados no armazenamento em nuvem à medida que se tornam disponíveis.
3) Pipeline de ingestão apenas de áudio
- O frontend valida que o usuário selecionou um dos mp3, m4a, flac, opus, wav.
- Inicie o trabalho via o endpoint de Download.
- Na conclusão, acione imediatamente a transcrição ou marcação a jusante, atento à janela de expiração de 2 horas para os links de áudio.
Usando esta API de um agente de IA via MCP
Se você preferir orquestrar chamadas de um agente de IA ou um IDE compatível com MCP, pode se conectar ao gateway MCP da Zyla. Clientes compatíveis com MCP, como Claude Code, Cursor e Windsurf, podem chamar APIs do marketplace usando sua chave de API Zyla. Revise os detalhes de conexão MCP aqui: MCP.
- Direcione seu cliente MCP para o endpoint MCP e forneça sua chave de API Zyla.
- Em seu prompt de ferramenta ou agente, instrua-o a fazer uma solicitação GET para a URL do endpoint de Download com os parâmetros url e format, e inclua o cabeçalho Authorization: Bearer YOUR_API_KEY.
- Analise success, id, image e progress_url da resposta para acionar ações subsequentes (por exemplo, polling ou atualizações de UI).
Lista de verificação de testes
- Valide URLs do YouTube e formatos do lado do cliente antes de chamar o endpoint.
- Faça uma chamada de teste com vídeo em 720p para confirmar que os campos success, id, image e progress_url são retornados conforme esperado.
- Implemente um tratamento básico de erros em torno dos códigos de status HTTP e timeouts.
- Decida onde armazenar o id do trabalho e com que frequência fazer polling na progress_url.
- Se expuser saídas de áudio, implemente uma dica ou lembrete de UX sobre a expiração de 2 horas do link de áudio resultante.
FAQ
Quais formatos são suportados?
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.
Os links de download de áudio expiram?
Sim. Os links de download de áudio expiram após 2 horas uma vez gerados. Projete sua UX de acordo.
Isso suporta transmissões ao vivo?
Este endpoint suporta o download apenas de vídeos regulares.
Como é tratado o faturamento?
As APIs Zyla usam um modelo de assinatura + cota, não pago por chamada. Para opções de acesso atuais (por exemplo, um teste de 7 dias ou 50 solicitações para sua primeira API), verifique a listagem do marketplace.
Envie isso
Inscreva-se e execute o cURL acima, depois conecte o id, image e progress_url ao seu rastreador de trabalhos. Você pode estar pronto para produção hoje. Comece aqui: Iniciar teste de 7 dias na API de Download e Informações do YouTube.
