Sua tarefa: pegue um link do YouTube ou ID de vídeo e busque programaticamente uma URL MP3 para download que você possa salvar ou transmitir em seu aplicativo. Ao final deste artigo, você chamará um endpoint real que retorna um link de áudio direto e metadados, e então escreverá algumas linhas de código para baixar o arquivo.
O que você pode construir com isso
A API Youtube to Audio no Zyla API Hub permite que você transforme um vídeo do YouTube em uma URL de download de áudio. Ela retorna um link para o arquivo de áudio junto com metadados úteis como título, duração e tamanho do arquivo. Os desenvolvedores a utilizam para:
- Gerar MP3s de vídeos públicos do YouTube para reprodução offline em um aplicativo de podcast ou aprendizado.
- Colocar em fila trabalhos de extração de áudio como parte de um fluxo de trabalho de mídia maior.
- Simplificar a ingestão de conteúdo retornando uma única URL que pode ser baixada ou proxyada pelo seu serviço.
Esta API foca em duas ações concretas: dado um ID de vídeo, retorna um link de áudio e metadados; ou, dado uma URL completa do YouTube, retorna uma URL pronta para download. Sem SDK para se preocupar, apenas chamadas simples HTTP GET.
Começando no Zyla API Hub
O Zyla API Hub fornece milhares de APIs prontas para produção através de uma conta, uma chave de API e um modelo de assinatura consistente. Você pode navegar, se inscrever e chamar APIs sem configurar várias contas de fornecedores. Explore mais em zylalabs.com.
Para usar esta API:
- Abra a página de início do teste de 7 dias na API Youtube to Audio no Zyla API Hub.
- Clique em Inscrever-se (ou Iniciar Teste Gratuito quando disponível) e obtenha sua chave de API.
- Envie solicitações com o cabeçalho Authorization: Bearer YOUR_API_KEY.
A cobrança é por assinatura com cota, não por chamada. Verifique a página da API para opções de acesso e preços atuais. Você também pode descobrir mais APIs e categorias em zylalabs.com.
Visão geral da API
A API Youtube to Audio expõe dois endpoints GET através do gateway da API da Zyla:
- Obter Áudio (por ID de vídeo do YouTube): retorna um link de áudio direto e metadados
- Baixar Áudio (por URL completa do YouTube): retorna uma URL de download
Todas as solicitações usam HTTPS e requerem o cabeçalho Authorization com uma chave de API Bearer. Os exemplos abaixo são copiáveis e coláveis.
Endpoint: Obter Áudio (por ID de vídeo)
Use isso quando você tiver o ID do vídeo do YouTube e precisar do link de áudio mais metadados como título, duração e tamanho do arquivo.
- Método: GET
- URL: https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio
- Parâmetro de consulta obrigatório: id
Exemplo de solicitação:
curl -s -X GET "https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio?id=xFYQQPAOz7Y" \
-H "Authorization: Bearer YOUR_API_KEY"
Exemplo de resposta JSON:
{
"msg": "success",
"link": "https://theta.123tokyo.xyz/get.php/d/fa/xFYQQPAOz7Y.mp3?n=Eminem%20-%20Lose%20Yourself&uT=R&uN=QWxlam9aeWxhTGFicw%3D%3D&h=TcO7xrzRPZ9cGbw2wXP93w&s=1784312338&uT=R&uN=QWxlam9aeWxhTGFicw%3D%3D",
"status": "ok",
"duration": 327.49718169275,
"title": "Eminem - Lose Yourself",
"progress": 100,
"pc": 0,
"filesize": 4181397
}
Notas de campo que você realmente usará:
- link: URL direta para o arquivo de áudio gerado. Use isso para transmitir ou salvar o MP3.
- title: título do vídeo fonte, útil para nomes de arquivos e rótulos de UI.
- duration: valor de ponto flutuante representando a duração em segundos.
- filesize: tamanho em bytes para o áudio baixável, que ajuda para barras de progresso e planejamento de armazenamento.
- status/msg/progress: indicadores de status; progress é um número semelhante a porcentagem neste exemplo.
Exemplo em Python: buscar link de áudio e baixar MP3
Este exemplo chama o endpoint Obter Áudio, extrai o campo link e baixa o arquivo para o disco. Substitua YOUR_API_KEY pela sua chave da página do marketplace.
import os
import sys
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
VIDEO_ID = "xFYQQPAOz7Y" # Fornecido na solicitação de exemplo
try:
# Passo 1: Obter metadados de áudio e link
meta_resp = requests.get(
"https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"id": VIDEO_ID},
timeout=30,
)
meta_resp.raise_for_status()
data = meta_resp.json()
if data.get("status") != "ok" or "link" not in data:
print("Áudio não está pronto ou falhou:", data)
sys.exit(1)
audio_url = data["link"]
title = data.get("title", f"{VIDEO_ID}.mp3")
duration = data.get("duration")
size_bytes = data.get("filesize")
# Escolha um nome de arquivo. Se o título estiver presente, faça um nome de arquivo seguro.
filename = f"{title}.mp3" if not title.endswith(".mp3") else title
safe_filename = filename.replace("/", "_")
print(f"Baixando: {safe_filename}")
print(f"Duração (s): {duration}")
print(f"Tamanho do arquivo (bytes): {size_bytes}")
print(f"URL: {audio_url}")
# Passo 2: Baixar o MP3
with requests.get(audio_url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(safe_filename, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print("Salvo em:", safe_filename)
except requests.HTTPError as e:
print("Erro HTTP:", e, file=sys.stderr)
sys.exit(1)
except requests.RequestException as e:
print("Falha na solicitação:", e, file=sys.stderr)
sys.exit(1)
Dica: como a resposta inclui filesize, você pode pré-alocar barras de progresso. Se filesize não estiver disponível, transmita e infira o progresso contando bytes enquanto escreve.
Endpoint: Baixar Áudio (por URL completa do YouTube)
Use isso quando você tiver uma URL completa do vídeo do YouTube e precisar apenas de uma URL de download. Este endpoint retorna um campo downloadUrl que você pode buscar em um segundo passo.
- Método: GET
- URL: https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio
- Parâmetro de consulta obrigatório: url
Exemplo de solicitação:
Exemplo de resposta JSON:
Em um fluxo típico, chame este endpoint para obter downloadUrl, depois execute um padrão HTTP GET nessa URL retornada para recuperar o conteúdo de áudio binário. Se você precisar de título, duração ou tamanho do arquivo, prefira o endpoint Obter Áudio que apresenta esses campos junto com o link.
Qual endpoint você deve usar?
- Use Obter Áudio quando você já tiver o ID do vídeo e quiser metadados (título, duração, filesize) mais o link em uma resposta.
- Use Baixar Áudio quando você tiver uma URL completa do YouTube e precisar apenas de uma URL baixável, depois busque o arquivo em uma segunda solicitação.
Detalhes de implementação que economizam tempo
- Autenticação: Sempre envie Authorization: Bearer YOUR_API_KEY. Não coloque a chave na string de consulta.
- Timeouts: Chamadas são padrões HTTPS GET. Defina timeouts práticos tanto na solicitação de metadados quanto na solicitação de download do arquivo. O download do arquivo pode demorar mais; transmita com leituras em pedaços.
- Nomes de arquivos: A resposta Obter Áudio inclui título, que é conveniente para nomes de arquivos. Sanitizar para seu SO.
- Durações e tamanhos: duration é um float em segundos; filesize é bytes. Use filesize para orçamento de armazenamento e indicadores de progresso.
- Cache: Se você solicitar repetidamente o mesmo ID de vídeo ou URL, armazene em cache o link e metadados resultantes em seu sistema com uma política de expiração que se encaixe no seu fluxo de trabalho.
- Tentativas: Solicitações de rede para o link de arquivo retornado atravessam um host diferente do gateway da Zyla. Se um download falhar, tente novamente com backoff.
Exemplo de ponta a ponta em JavaScript (Node.js)
Este script usa fetch para acessar o endpoint Obter Áudio, depois baixa o arquivo usando o link retornado. Use Node 18+ ou adicione um polyfill de fetch.
import fs from "node:fs";
import { pipeline } from "node:stream";
import { promisify } from "node:util";
const streamPipeline = promisify(pipeline);
const API_KEY = process.env.ZYLA_API_KEY || "YOUR_API_KEY";
const VIDEO_ID = "xFYQQPAOz7Y";
async function main() {
// Passo 1: Obter metadados + link
const metaUrl = new URL("https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio");
metaUrl.searchParams.set("id", VIDEO_ID);
const metaResp = await fetch(metaUrl, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!metaResp.ok) {
console.error("Falha na solicitação de metadados:", metaResp.status, await metaResp.text());
process.exit(1);
}
const data = await metaResp.json();
if (data.status !== "ok" || !data.link) {
console.error("Áudio não está pronto ou link ausente:", data);
process.exit(1);
}
const audioUrl = data.link;
const title = data.title || `${VIDEO_ID}.mp3`;
const filename = title.endsWith(".mp3") ? title : `${title}.mp3`;
console.log("Baixando:", filename);
console.log("Duração (s):", data.duration);
console.log("Tamanho do arquivo (bytes):", data.filesize);
console.log("URL:", audioUrl);
// Passo 2: Baixar o arquivo
const fileResp = await fetch(audioUrl, { method: "GET" });
if (!fileResp.ok || !fileResp.body) {
console.error("Download falhou:", fileResp.status, await fileResp.text());
process.exit(1);
}
await streamPipeline(fileResp.body, fs.createWriteStream(filename));
console.log("Salvo em:", filename);
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
Padrões do mundo real
- Processamento em lote: Dada uma playlist, resolva cada vídeo para seu ID, depois chame Obter Áudio para cada ID. Armazene título, filesize e link para seu pipeline de ingestão.
- Microlibrary para seu serviço: Envolva esses dois endpoints em um pequeno helper com retry, timeout e sanitização de nomes de arquivos.
- Trabalhos em segundo plano: Coloque em fila conversões de ID para áudio usando seu executor de trabalhos. Se data.status ou progress indicarem trabalho assíncrono em seu cenário, faça polling até que o progresso seja 100 antes de baixar.
- Transferência de armazenamento: Em vez de servir o link externo diretamente, baixe e reenvie para seu próprio armazenamento de objetos para hospedagem e controle de acesso consistentes.
Chamando de agentes de IA via MCP
Se você está conectando isso a um ambiente de desenvolvedor de IA, pode chamar as APIs da Zyla através do Protocolo de Contexto do Modelo usando um único endpoint MCP. Qualquer cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf) pode invocar APIs do marketplace através de:
Endpoint para agentes: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Use sua chave de API Zyla com o parâmetro de consulta apikey nesse endpoint MCP, e então faça seu agente realizar as mesmas chamadas HTTPS mostradas acima através de seu transporte MCP. Para informações gerais sobre MCP, veja a página MCP.
Lista de verificação de solução de problemas
- Erros 401 ou 403: Certifique-se de que o cabeçalho Authorization está definido como Bearer YOUR_API_KEY e que sua assinatura está ativa.
- Nenhum link na resposta: Para o endpoint Obter Áudio, verifique os campos de status e progresso e tente novamente após um curto atraso, se necessário.
- Download falha durante a transmissão: Tente novamente a solicitação do arquivo com backoff e considere verificar tamanhos de arquivos parciais.
- Títulos ou nomes de arquivos inesperados: Sanitize caracteres especiais e volte para o ID do vídeo se o título estiver ausente.
Notas de segurança e operacionais
- Nunca insira sua chave de API no código do lado do cliente. Proxie solicitações através do seu backend ou use chamadas do lado do servidor.
- Registre IDs de solicitações e timestamps com suas chamadas para simplificar a depuração e suporte.
- Considere a política de conteúdo e permissões do usuário para qualquer distribuição posterior do áudio baixado.
Próximos passos
Uma vez que você verifique sua primeira solicitação, envolva essas chamadas na camada de serviço do seu aplicativo, adicione tentativas mínimas e conecte eventos de progresso à sua UI. Use os campos de título, duração e filesize para rotular e monitorar o processamento de áudio.
Para experimentar agora, abra a página do marketplace e obtenha uma chave de API: Iniciar teste de 7 dias na API Youtube to Audio. Você terá acesso baseado em assinatura com uma cota. Verifique a página da API para opções de acesso e preços atuais.
FAQ
Qual cabeçalho de autenticação é necessário?
Envie Authorization: Bearer YOUR_API_KEY em cada solicitação para o endpoint Zyla.
Qual endpoint retorna metadados como título e duração?
Use GET https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio com o parâmetro id.
Como faço para baixar o arquivo de áudio real?
Chame um dos endpoints da API para obter um link ou downloadUrl, depois execute um padrão HTTP GET nessa URL retornada para recuperar o conteúdo binário.
Posso começar com uma URL completa do YouTube em vez de um ID?
Sim. Use GET https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio com o parâmetro url.
Há um plano gratuito?
O acesso é por assinatura com cota. A página do item oferece um teste de 7 dias quando disponível. Verifique a página da API para opções de acesso e preços atuais.