YouTube DL API — Documentação

REST API completa para download de vídeo/áudio do YouTube, Blogger e 1100+ sites via yt-dlp — com progresso em tempo real (SSE) e link pronto para compartilhar.

v4.0.0 REST SSE streaming multi-plataforma by @lucas_mod_domina
URL base (produção): https://yt-api.zero-two-apis.store  ·  ← Painel interativo (testar rotas ao vivo)  ·  /sites — plataformas suportadas
NOVO APLICATIVO ZERO TWO

Zero Two Music

Use sua própria apikey para pesquisar e reproduzir músicas, vídeos, lives e playlists com player moderno, notificações e reprodução em segundo plano.

↓ Carregando APK Android… Consultando o link oficial configurado no servidor.
Como instalar e começar
  1. Abra esta documentação no celular Android e toque em Baixar APK Android.
  2. Permita a instalação pelo navegador ou gerenciador de arquivos quando solicitado.
  3. Instale o Zero Two Music e entre com sua própria apikey.
  4. Use Configurações e privacidade para controlar compartilhamento e console de consumo.

O download atual é para Android. Uma versão iOS pública exige macOS/Xcode e Apple Developer Program.

📑 Índice

🔑 Autenticação 🚀 Quick start (cURL · JS · Node · Python · PHP) 📡 Consumindo rotas SSE (progresso ao vivo) 📦 Formato das respostas 🎬 Rotas YouTube 🌍 Rotas multi-plataforma (1100+ sites) 📝 Rotas Blogger ⚙️ Rotas avançadas 📃 Rotas de playlist 🔎 Busca YouTube 🧰 Utilidades 🤖 Usando em bots (WhatsApp · Discord) ⚠️ Erros & boas práticas 🛡️ Administração (cookies via API)

🔑 Autenticação

Quase todas as rotas exigem uma API key. Passe como query param apikey em qualquer chamada:

GET /audio?url=https://www.youtube.com/watch?v=XXXX&apikey=SUA_KEY

Rotas públicas (não pedem key): /, /docs, /health, /meta, /stats, /detailed-stats, /deps, /endpoints, /config/site, /sites, /cleanup-stats.

Adquira sua key em zero-two-apis.com.br. Cada requisição bem-sucedida debita 1 request do seu saldo. Keys inativas por 30 dias são removidas automaticamente.

🚀 Quick start — um download em cada linguagem

cURL

# Áudio do YouTube direto para arquivo
curl "https://yt-api.zero-two-apis.store/audio?url=https://www.youtube.com/watch?v=146RCHTZld4&apikey=SUA_KEY" -H "Accept: application/json"

# Vídeo do Instagram (SSE — veja a seção de streaming)
curl -N "https://yt-api.zero-two-apis.store/instagram?url=https://www.instagram.com/reel/C7XYZabc123/&apikey=SUA_KEY"

JavaScript (fetch — browser ou Node 18+)

const r = await fetch(
`https://yt-api.zero-two-apis.store/extract/info?url=${encodeURIComponent(url)}&apikey=SUA_KEY`
);
const json = await r.json();
if (json.status) console.log(json.resultados.title, json.resultados.formats.best_progressive?.url);

Node.js (axios, consumindo SSE)

const axios = require('axios');

const { data: stream } = await axios.get(
'https://yt-api.zero-two-apis.store/shorts',
{ params: { url: 'https://youtube.com/shorts/146RCHTZld4', apikey: 'SUA_KEY' } }
);
// /shorts responde JSON único:
console.log(stream.resultados.direct); // https://...mp4 (link de download)

Python (requests)

import requests

r = requests.get('https://yt-api.zero-two-apis.store/info', params={
'url': 'https://www.youtube.com/watch?v=146RCHTZld4',
'apikey': 'SUA_KEY'
}, timeout=60)
data = r.json()
print(data['resultados']['title'])

PHP

$ch = curl_init('https://yt-api.zero-two-apis.store/extract/info?url='
. urlencode('https://www.tiktok.com/@user/video/7123...')
. '&apikey=SUA_KEY');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $json['resultados']['title'];

📡 Consumindo rotas SSE (progresso ao vivo)

As rotas de processamento pesado respondem Content-Type: text/event-stream e enviam eventos data: {...}\n\n de progresso até o evento final padronizado (que contém o link) — ou um evento com status: "error" em caso de falha.

Formato final padronizado de TODAS as rotas de download (/download, /extract/download, aliases, /video/mp4, /sponsorblock, /multi-stream, /external-downloader, /download-sections, /split-chapters):

{
"status": "completed",
"done": true,
"criador": "@lucas_mod_domina",
"resultados": { "url": "https://...", "title": "...", "size": "...", "...": "campos variam por rota" }
}

As rotas de playlist em lote (/playlist/audio, /playlist/video) seguem padrão próprio: um evento por item (completed/ready com url no topo) e encerram com { "status"/"type": "done", "done": true, ... }.

Rotas SSE: /download, /download-sections, /split-chapters, /sponsorblock, /multi-stream, /external-downloader, /video/mp4, /playlist/audio, /playlist/video, /extract/download e os aliases de plataforma (/instagram, /tiktok…).

JavaScript (lendo o stream)

const res = await fetch(url_com_apikey);
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = '';
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += value;
const evts = buf.split('\n\n');
buf = evts.pop(); // resto incompleto espera o próximo chunk
for (const e of evts) {
if (!e.startsWith('data: ')) continue;
const evt = JSON.parse(e.slice(6));
if (evt.status === 'completed') console.log('LINK:', evt.resultados?.url || evt.url);
else if (evt.status === 'error') console.error(evt.error);
else console.log(evt.progress, evt.status); // progresso
}
}

Python (requests stream)

import requests, json

with requests.get(url, params={...}, stream=True, timeout=600) as r:
for line in r.iter_lines(decode_unicode=True):
if line and line.startswith('data: '):
evt = json.loads(line[6:])
if evt.get('status') == 'completed':
print('LINK:', (evt.get('resultados') or {}).get('url') or evt.get('url'))
🕒 Downloads podem levar de segundos a alguns minutos (depende do tamanho e do upload). Use timeout alto (600s) no seu cliente HTTP e não encerre a conexão antes do evento completed.

📦 Formato das respostas

Rotas JSON seguem o padrão:

{
"status": true,
"criador": "@lucas_mod_domina",
"resultados": { ... }
}

Em erro: {"status": false, "error": "...", "message": "..."} (HTTP 4xx/5xx). O evento SSE final traz resultados.url (link de download), resultados.expires (validade do link) e resultados.uploadedTo (Catbox · Litterbox · Dropbox · Gofile · local).

🎬 Rotas YouTube

RotaParamsResposta
GET /infourlMetadados completos do vídeo
GET /formatsurlLista bruta de formatos (yt-dlp --list-formats)
GET /audiourlJSON com link direto do melhor áudio
GET /audio/mp3urlArquivo MP3 (128k, compatível c/ WhatsApp) — download direto
GET /audio/pipeurlStream binário do áudio (m4a/webm)
GET /videourlVídeo muxado; upload e link
GET /video/mp4 SSEurlRe-encode alta qualidade (H.264 CRF18)
GET /short · /shortsurlShort em MP4 H.264/AAC + link (cache 6h)
GET /liveurl, from_startURL HLS/stream da live

Exemplo real — Short

GET /shorts?url=https://youtube.com/shorts/146RCHTZld4&apikey=SUA_KEY

{
"status": true,
"resultados": {
"direct": "https://gofile.io/d/trU950",
"expires": "Temporário (Página de Download)",
"filename": "short_1786432811370_wc7ecouvm9q.mp4",
"title": "ele achou que era Malandro... 😂",
"resolution_original": "1080x1920"
}
}

🌍 Rotas multi-plataforma (1100+ sites)

Funcionam com qualquer site suportado pelo yt-dlp — Instagram, TikTok, Twitter/X, Facebook, Pinterest, Kwai, Reddit, Twitch, Vimeo, SoundCloud, Dailymotion e centenas mais (lista completa em /sites).

RotaParamsResposta
GET /extract/infourlMetadados + melhores formatos de qualquer site
GET /extract/download SSEurl, quality, formatDownload universal + link
GET /sites pública—Extratores suportados (1100+) + destaques
GET aliases SSE/instagram · /tiktok · /twitter · /facebook · /pinterest · /kwai · /reddit · /twitch · /vimeo · /soundcloud · /dailymotion — mesmos params de /extract/download

Params de download: quality = best (padrão) · 1080p · 720p · 480p · 360p · worst  |  format = mp4 (padrão) · mp3 (só o áudio)

Exemplo real — TikTok

GET /tiktok?url=https://www.tiktok.com/@usuario/video/7234567890123456789&format=mp3&apikey=SUA_KEY

# eventos SSE:
data: {"progress":5,"status":"Plataforma detectada: TikTok"}
data: {"progress":15,"status":"Baixando melhor áudio..."}
data: {"progress":92,"status":"[UPLOAD] ✓ Gofile — https://gofile.io/d/xxxxx"}
data: {"status":"completed","done":true,"criador":"@lucas_mod_domina","resultados":{"url":"https://gofile.io/d/xxxxx","size":"2.9 MB","platform":"TikTok","format":"mp3"}}

📝 Rotas Blogger

Extrator dedicado (yt-dlp PR #17129, rodando via Python local — veja /deps → ytdlp_blogger). Aceita tanto blogger.com/video.g?token=... quanto posts de blog com vídeo embutido.

RotaParamsResposta
GET /blogger/infourlMetadados + melhor link progressivo
GET /blogger/downloadurl, quality, formatDownload (mp4/mp3) + link
GET /blogger/download?url=https://blog.tomeuvizoso.net/2019/01/a-panfrost-milestone.html&quality=720p&apikey=SUA_KEY

⚙️ Rotas avançadas (todas SSE)

RotaParams principaisO que faz
GET /downloadurl, quality, format, extractAudio, audioFormat, limitRate...Download universal do YouTube com todas as opções
GET /download-sectionsurl, sections (ex.: *10:15-15:30)Baixa só trechos do vídeo
GET /split-chaptersurlDivide o vídeo em capítulos
GET /sponsorblockurl, mark ou remove (ex.: sponsor,intro,outro)Remove/marca propaganda automaticamente
GET /multi-streamurl...Combina múltiplos streams
GET /external-downloaderurl, downloader (aria2c...), concurrentFragmentsUsa downloader externo p/ máxima velocidade
GET /dlurl, type?Legado: auto-detecta vídeo/áudio/short
# Só o trecho 1:00–2:30 de um vídeo
GET /download-sections?url=...&sections=*1:00-2:30&apikey=SUA_KEY

# Vídeo limpo sem publicidade nem intro
GET /sponsorblock?url=...&remove=sponsor,intro,outro&apikey=SUA_KEY

📃 Rotas de playlist

RotaParamsResposta
GET /playlist/infourlMetadados + itens (título, duração, thumbs)
GET /playlist/audio SSEurl, audioFormat...Link de áudio por item, emitido em tempo real
GET /playlist/video SSEurlURL pronta de /video por item

🔎 Busca YouTube

RotaParamsResposta
GET /api/ytsrcq (ou query)Vídeos, canais e playlists encontrados
GET /api/ytsrc/videosqApenas vídeos
GET /api/ytsrc?q=lofi%20hip%20hop&apikey=SUA_KEY → { status: true, resultado: [ { title, url, duration ... }, ... ] }

🧰 Utilidades (públicas)

RotaResposta
GET /healthonline + horário BRT
GET /metaruntime: ffmpeg/yt-dlp/cloudflared/blogger/memória
GET /depsversões e status de cada dependência + análise de cookies
GET /stats · /detailed-statsmétricas de uso
GET /endpointsesta lista de rotas em JSON (o painel consome daqui)

🤖 Usando em bots

WhatsApp (Baileys)

// npm i @whiskeysockets/baileys axios
if (text.startsWith('!play ')) {
const q = text.slice(6);
const s = await axios.get('https://yt-api.zero-two-apis.store/api/ytsrc', { params: { q, apikey } });
const v = s.data.resultado.videos[0];
const a = await axios.get('https://yt-api.zero-two-apis.store/audio/mp3',
{ params: { url: v.url, apikey }, responseType: 'arraybuffer' });
await sock.sendMessage(jid, { audio: Buffer.from(a.data), mimetype: 'audio/mpeg' });
}

Discord.js (v14)

const { data } = await axios.get('https://yt-api.zero-two-apis.store/extract/info',
{ params: { url: linkDoUsuario, apikey: process.env.YTDL_KEY } });
await interaction.reply(
`🎬 ${data.resultados.title}\n⬇️ ${data.resultados.formats.best_progressive?.url ?? 'sem progressivo — use /extract/download'}`
);
Nunca exponha sua API key no frontend público ou no repositório do bot — chame a API pelo backend/bot e entregue só o link final ao usuário.

⚠️ Erros comuns & boas práticas

ErroCausa / solução
401 API key inválidaKey errada, esgotada ou excluída por 30 dias de inatividade
429 RATE_LIMITMáx. 120 req/min por IP — aguarde 1 minuto
verificação anti-bot / 403Cookies do servidor expiraram — o admin reexporta o cookies.txt
A plataforma pediu loginPost privado/protegido (Instagram/TikTok): requer cookies daquela rede no servidor
Conteúdo indisponívelVídeo removido, privado ou região bloqueada
Timeout (504)Mídia muito longa/pesada — tente quality=360p ou uma rota mais leve
Boas práticas: 1) Chame /extract/info antes do download para confirmar título/duração. 2) Links de upload temporários (Litterbox 24h, Gofile ~dias) — baixe o arquivo logo após receber. 3) Em SSE, consuma até o evento completed; desconectar antes cancela o processamento no servidor. 4) Playlists grandes (100+ itens) levam vários minutos em /playlist/audio — considere processar itens individualmente.

⚠️ Limitações conhecidas (estado do yt-dlp upstream)

🛡️ Administração (rotas protegidas)

Rotas de manutenção do servidor, protegidas por token de admin. Ative definindo ADMIN_TOKEN=uma-senha-forte no .env e reinicie. Sem a variável, as rotas respondem 503. Autentique via header Authorization: Bearer <TOKEN> ou query ?token=<TOKEN>.

RotaDescrição
GET /admin/cookies/statusEstado dos cookies: total, expirados, expirando em 7 dias, sessão autenticada?, domínios cobertos e dias até o vencimento mais próximo.
POST /admin/cookies/refreshTroca o cookies.txt em produção sem restart. Aceita o arquivo Netscape (cookies.txt) ou o JSON da extensão "Get cookies.txt LOCALLY" — detecta e converte automaticamente. Faz backup do arquivo anterior (cookies.txt.bak-*), valida antes de aplicar e rejeita arquivos sem nenhum cookie válido.

Exemplo — trocar cookies pelo terminal (VPS, Termux ou PC)

curl -X POST "https://yt-api.zero-two-apis.store/admin/cookies/refresh" \
-H "Authorization: Bearer SUA_SENHA_ADMIN" \
-H "Content-Type: text/plain" \
--data-binary @cookies.txt
Importante: use --data-binary (não -d) e o header Content-Type: text/plain para preservar os tabs do formato Netscape. Para mandar o JSON da extensão, use Content-Type: application/json.

Exemplo — checar saúde dos cookies

curl "https://yt-api.zero-two-apis.store/admin/cookies/status?token=SUA_SENHA_ADMIN"
⚠️ Nunca use pacotes de "cookies compartilhados" de terceiros (ex.: yt-cookies do PyPI): eles baixam cookies de sessão de contas de pessoas desconhecidas vindos de um servidor remoto — risco de fraude, banimento da sua VPS e vazamento de dados. O correto é exportar os seus cookies do seu navegador e enviar por esta rota, ou deixar o PO Token provider cuidar do anti-bot automaticamente.