Você precisa de uma API para transformar programaticamente um vídeo do YouTube em um arquivo de áudio e enviá-lo esta semana. Ao final deste artigo, você terá um código funcional em curl e Python que retorna um link direto para download em MP3 a partir de uma URL ou ID do YouTube, e você saberá como integrá-lo em seu pipeline de mídia usando o Zyla API Hub.
O que esta API faz (e por que é importante para integrações de mídia)
A API de Youtube para Áudio converte um vídeo do YouTube em um arquivo de áudio e retorna um link de download direto, além de metadados úteis (título, duração, tamanho do arquivo). Ela expõe dois endpoints simples: um aceita um ID de vídeo do YouTube; o outro aceita uma URL completa do YouTube. Isso é ideal para:
- Ingestão de podcast ou palestra: extraia MP3 para transcrição ou sumarização a jusante.
- Fluxos de trabalho de recorte de áudio: busque áudio para cortar segmentos, normalizar ou misturar.
- Gerenciamento de conteúdo: arquive versões de áudio de conteúdo em vídeo para pesquisa interna ou conformidade.
- Ferramentas agentivas: permita que um agente de IA extraia áudio quando um usuário enviar um link do YouTube.
Você chamará os endpoints via HTTPS no Zyla API Hub usando uma única chave que você pode reutilizar em todo o marketplace.
Começando no Zyla API Hub
Abra a página da API para a API de Youtube para Áudio e inscreva-se. O hub usa um modelo de assinatura + cota, não pagamento por chamada. Não há Plano Gratuito; a primeira API normalmente oferece um teste de 7 dias ou 50 solicitações para desbloqueá-lo. Após se inscrever, você receberá uma chave de API. Todas as solicitações neste artigo usam o cabeçalho Authorization: Bearer YOUR_API_KEY.
Vá aqui para começar: Comece o teste de 7 dias na API de Youtube para Áudio. Você também pode navegar por mais de 10.000 APIs públicas no marketplace do Zyla API Hub com uma conta e uma chave de API.
Endpoints que você usará
A API expõe dois endpoints GET no Zyla API Hub. Ambos requerem o cabeçalho Authorization. Apenas os parâmetros listados abaixo são suportados.
1) Obter Áudio (por ID de vídeo do YouTube)
- Método: GET
- URL: https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio
- Parâmetro obrigatório: id (string) — o ID do vídeo do YouTube.
- Descrição: Forneça um ID de vídeo do YouTube para receber um link direto em MP3 e metadados.
exemplo de curl (copiar-colar):
curl -s -X GET "https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio?id=xFYQQPAOz7Y" \
-H "Authorization: Bearer YOUR_API_KEY"Resposta de exemplo oficial:
{
"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 MP3 gerado; você pode transmiti-lo ou baixá-lo.
- title: Título do vídeo (útil para padrões de nome de arquivo).
- duration: Duração do áudio em segundos (ponto flutuante).
- filesize: Tamanho do arquivo de áudio em bytes.
- status e msg: Status operacional; útil para verificações simples de sucesso.
2) Baixar Áudio (por URL completa do YouTube)
- Método: GET
- URL: https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio
- Parâmetro obrigatório: url (string) — URL completa do YouTube.
- Descrição: Forneça uma URL completa do YouTube para recuperar uma URL de áudio para download.
exemplo de curl (copiar-colar):
Resposta de exemplo oficial:
Notas de campo:
- downloadUrl: Uma URL que você pode GET para baixar o áudio do vídeo do YouTube fornecido.
Quando usar cada endpoint
- Já tem o ID do vídeo (por exemplo, “xFYQQPAOz7Y”)? Use Obter Áudio. Você receberá um link direto em MP3, além de duração, título, progresso e tamanho do arquivo.
- Tem uma URL completa do YouTube (por exemplo, https://www.youtube.com/watch?v=_Yhyp-_hX2s)? Use Baixar Áudio. Você receberá uma URL para download desse recurso.
Se você precisar de metadados (duração/título/tamanho do arquivo) junto com o link, prefira Obter Áudio com o ID. Se suas entradas forem URLs coladas pelo usuário, comece com Baixar Áudio para um pré-processamento mínimo.
Um exemplo funcional em Python
Este exemplo em Python demonstra como chamar o endpoint Obter Áudio, validar a resposta e baixar o MP3 para o disco usando o link retornado. Substitua YOUR_API_KEY pela sua chave da página da API.
import os
import sys
import json
import time
import urllib.parse
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
VIDEO_ID = "xFYQQPAOz7Y" # ID de exemplo; substitua na produção
def get_audio_by_id(video_id: str):
url = "https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio"
params = {"id": video_id}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, headers=headers, params=params, timeout=60)
resp.raise_for_status()
return resp.json()
def download_file(file_url: str, out_path: str):
with requests.get(file_url, stream=True, timeout=300) as r:
r.raise_for_status()
with open(out_path, "wb") as f:
for chunk in r.iter_content(chunk_size=1_048_576): # 1MB
if chunk:
f.write(chunk)
def main():
data = get_audio_by_id(VIDEO_ID)
# Verificações básicas com base nos campos documentados
if data.get("status") != "ok" or data.get("msg") != "success":
print("Conversão não bem-sucedida:", json.dumps(data, indent=2))
sys.exit(1)
link = data.get("link")
title = data.get("title") or VIDEO_ID
duration = data.get("duration")
size_bytes = data.get("filesize")
if not link:
print("Nenhum link de download retornado:", json.dumps(data, indent=2))
sys.exit(1)
# Crie um nome de arquivo seguro
safe_title = "".join(c for c in title if c.isalnum() or c in (" ", "-", "_")).strip()
filename = f"{safe_title or VIDEO_ID}.mp3"
print(f"Baixando: {title} ({duration:.2f}s, {size_bytes} bytes)")
download_file(link, filename)
print(f"Salvo em {filename}")
if __name__ == "__main__":
main()Notas:
- O cabeçalho Authorization é necessário para ambos os endpoints.
- Duração é um número de ponto flutuante em segundos.
- filesize é em bytes; use-o para barras de progresso ou verificações de cota de disco.
- Transmita downloads grandes para evitar carregar o arquivo inteiro na RAM.
Dicas práticas e detalhes de integração
- Estratégia de repetição: Saltos de rede para links de download de terceiros podem ter falhas intermitentes. Envolva o download final do arquivo em uma repetição com retrocesso exponencial.
- Segurança do nome do arquivo: Use o título retornado, mas sane para evitar caracteres inválidos do sistema de arquivos.
- Cache: Se você processar o mesmo recurso do YouTube repetidamente, armazene em cache o MP3 final do seu lado, indexado pelo ID do vídeo para economizar tempo e cota.
- Persistência de metadados: Armazene duração e tamanho do arquivo com seu registro de ativo para alimentar elementos de UX como tempo estimado de download.
- Trabalhos em segundo plano: Execute conversões e downloads de forma assíncrona para manter as latências da API fora do seu caminho de solicitação.
Fluxos de trabalho de mídia comuns que você pode enviar esta semana
- Pipeline de transcrição: Use Baixar Áudio em uma URL do YouTube colada, busque o MP3 e, em seguida, entregue-o à sua ferramenta de reconhecimento de fala.
- Gerador de trechos: Use Obter Áudio para puxar áudio e metadados, depois corte teasers de 30–60s para distribuição social.
- Ingestão de conhecimento: Converta regularmente conteúdo educacional de longa duração em MP3s para indexação a jusante e pesquisa semântica.
- Transferência de agente: Deixe um chatbot aceitar uma URL do YouTube, chamar a API e retornar um link de áudio para o usuário baixar.
Chamando esta API de um agente de IA via MCP
Todo Zyla API pode ser chamado de agentes de IA que suportam o Protocolo de Contexto de Modelo (MCP). Aponte seu cliente compatível com MCP para o endpoint MCP com sua chave como um parâmetro de consulta: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. A partir daí, seu agente pode emitir as mesmas chamadas HTTPS para os endpoints da API de Youtube para Áudio mencionados acima. Para detalhes de configuração do agente, consulte o recurso MCP.
Fluxo típico para agentes:
- Aceitar entrada do usuário (URL ou ID do YouTube).
- Escolher o endpoint correspondente (Obter Áudio para IDs; Baixar Áudio para URLs completas).
- Retornar o link final de download em MP3 de volta para o usuário ou para a próxima ferramenta na cadeia.
Solução de problemas
- 401 Não autorizado: Certifique-se de que o cabeçalho Authorization esteja presente e que o token bearer seja sua chave ativa do marketplace.
- Parâmetro ausente ou inválido: Cada endpoint requer exatamente um parâmetro (id para Obter Áudio, url para Baixar Áudio). Verifique a formatação e a codificação de URL para strings de consulta.
- Downloads lentos: Transmita o arquivo e considere um CDN do seu lado se redistribuir ativos para muitos usuários.
- Planejamento de cota: O marketplace usa assinatura + cota. Monitore seu uso e escolha um plano que cubra seu volume de conversão semanal. Verifique a página da API para opções de acesso e preços atuais.
Lembretes de segurança e conformidade
- Respeite os direitos e termos de conteúdo ao converter e armazenar áudio.
- Regenerar links de download sob demanda em vez de codificar URLs de terceiros que podem expirar.
- Armazene apenas o que você precisa: armazene em cache o áudio e metadados mínimos (título, duração, tamanho do arquivo) para seu caso de uso.
Copiar-colar: trecho mínimo de JavaScript fetch
Se você prefere JavaScript, aqui está um pequeno exemplo direcionando Obter Áudio por ID e registrando o link direto em MP3:
const API_KEY = "YOUR_API_KEY";
const videoId = "xFYQQPAOz7Y";
async function getAudioLinkById(id) {
const url = new URL("https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio");
url.searchParams.set("id", id);
const resp = await fetch(url.toString(), {
method: "GET",
headers: { "Authorization": `Bearer ${API_KEY}` }
});
if (!resp.ok) {
throw new Error(`HTTP ${resp.status}`);
}
const data = await resp.json();
if (data.status !== "ok" || data.msg !== "success" || !data.link) {
throw new Error(`Conversão não pronta ou falhou: ${JSON.stringify(data)}`);
}
return {
mp3Url: data.link,
title: data.title,
durationSec: data.duration,
sizeBytes: data.filesize
};
}
getAudioLinkById(videoId)
.then(info => {
console.log("URL MP3:", info.mp3Url);
console.log("Título:", info.title);
console.log("Duração (s):", info.durationSec);
console.log("Tamanho (bytes):", info.sizeBytes);
})
.catch(err => {
console.error("Erro:", err);
});Listas de verificação para envio
Para um trabalho de ingestão em lote
- Normalização de entrada: Converta qualquer URL do YouTube colada em um ID quando precisar de metadados (Obter Áudio), ou passe a URL como está (Baixar Áudio).
- Paralelismo: Controle as conversões e downloads concorrentes para corresponder à sua capacidade de computação e rede.
- Chaves de armazenamento: Use o ID do vídeo do YouTube como a chave de ativo canônica em todo o seu sistema.
- Tratamento de erros: Em falhas transitórias, repita o download final do arquivo; em erros 4xx, registre e pule.
Para um botão de download acionado pelo usuário
- Chamada do servidor: Acesse o endpoint do lado do servidor, não do navegador, para proteger sua chave de API.
- URLs temporárias: Busque um link fresco ao clicar para evitar URLs obsoletas.
- UI de progresso: Use o tamanho do arquivo para calcular o progresso e a duração para estimativas de “tempo restante”.
Recapitulação: endpoints exatos a serem usados
- GET https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio?id=YOUR_VIDEO_ID — retorna link, título, duração, progresso, tamanho do arquivo.
- GET https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio?url=YOUR_YOUTUBE_URL — retorna downloadUrl para a URL do vídeo fornecida.
Cabeçalho de autenticação para ambos: Authorization: Bearer YOUR_API_KEY.
FAQ
Q: Preciso da URL completa ou apenas do ID do vídeo?
A: Use Obter Áudio se você tiver o ID do vídeo e quiser metadados com o link MP3. Use Baixar Áudio se você tiver a URL completa do YouTube.
Q: O que o tamanho do arquivo representa?
A: É o tamanho do MP3 em bytes. Use-o para estimar necessidades de largura de banda e renderizar barras de progresso.
Q: Posso chamar isso de um agente de IA?
A: Sim. Aponte seu cliente compatível com MCP para o endpoint MCP (https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY) e faça o agente chamar as mesmas URLs da API mostradas acima.
Q: Como a cobrança é tratada?
A: A Zyla usa um modelo de assinatura + cota, não pagamento por chamada. Não há Plano Gratuito. A primeira API normalmente oferece um teste de 7 dias ou 50 solicitações para começar. Verifique a página da API para opções de acesso e preços atuais.
Q: Quais cabeçalhos eu preciso?
A: Inclua Authorization: Bearer YOUR_API_KEY em cada solicitação.
Pronto para implementar seu fluxo de mídia? Obtenha sua chave e comece a converter vídeos em MP3 agora: Comece o teste de 7 dias na API de Youtube para Áudio.
