youtube-transcript-api bloqueado pelo YouTube? 4 soluções que funcionam

O erro: funciona no local, bloqueia em produção

A biblioteca Python youtube-transcript-api é a forma mais popular de buscar transcrições do YouTube de forma programática. Na sua máquina, ela costuma funcionar sem falhas. Mas assim que o código roda em um servidor na nuvem, as requisições começam a falhar com exceções como IpBlocked, RequestBlocked ou TooManyRequests — em geral com uma mensagem sugerindo que o YouTube bloqueou o seu IP.

O mesmo acontece com qualquer abordagem baseada em scraping: pacotes de transcrição em Node.js, extração de legendas com yt-dlp e scrapers caseiros batem exatamente na mesma parede. O gatilho não é o seu código — é de onde as suas requisições saem.

Se a sua carga roda em AWS Lambda, Google Cloud Run, Vercel, Railway, Fly.io ou em qualquer VPS, o YouTube enxerga um IP de datacenter. Essas faixas de IP são de conhecimento público, muito abusadas por bots e bloqueadas em massa. Conexões residenciais (como o Wi-Fi da sua casa) raramente são bloqueadas — e é por isso que o clássico "na minha máquina funciona" é literalmente verdade aqui.

Por que o YouTube bloqueia essas requisições

As transcrições do YouTube são servidas por um endpoint interno e sem autenticação, que nunca foi pensado para uso por terceiros. Não existe uma API pública oficial para buscar a transcrição de um vídeo qualquer: o endpoint de legendas da Data API oficial exige autorização OAuth do dono do vídeo, ou seja, só funciona para os seus próprios vídeos.

Como o endpoint interno é gratuito e não autenticado, ele é martelado por empresas de IA, ferramentas de SEO e scrapers. O YouTube reage da única forma que pode — limitação agressiva de taxa, bloqueio em massa de faixas de IP de datacenter e mudanças ocasionais no endpoint que quebram as bibliotecas de scraping da noite para o dia.

Ou seja: qualquer solução self-hosted vive um jogo permanente de gato e rato. As quatro soluções abaixo estão ordenadas da mais caseira para a mais gerenciada.

Solução 1: enviar as requisições por proxies residenciais

A correção caseira padrão é rotear as requisições por proxies residenciais rotativos, para que o YouTube veja IPs domésticos comuns em vez do seu servidor. As versões recentes da youtube-transcript-api suportam isso nativamente: basta passar uma configuração de proxy (a biblioteca traz o helper WebshareProxyConfig, ou use GenericProxyConfig com qualquer proxy HTTP/SOCKS) na construção do cliente.

Funciona, mas tem custo real. A banda de proxy residencial é cara (normalmente alguns dólares por GB), a qualidade varia muito entre fornecedores e você passa a ser dono de um novo modo de falha: quando um IP de proxy é bloqueado no meio da requisição, você precisa de lógica de retry, health checks e failover entre provedores. Em volumes baixos, também pode ser a opção mais lenta, já que cada requisição ganha um salto extra pela rede de proxies.

Escolha esta opção se você precisa de controle total, tem tempo de engenharia para manter isso de pé e o seu volume justifica o esforço.

Solução 2: rodar o coletor em uma conexão residencial

Uma variação mais simples: rode a parte do pipeline que busca as transcrições em algum lugar com IP residencial — um Raspberry Pi em casa, uma máquina do escritório ou um mini PC barato — e faça essa máquina empurrar os resultados para a sua infraestrutura na nuvem por uma fila ou um webhook.

Isso elimina o custo de proxy e funciona surpreendentemente bem para cargas pequenas e pessoais (transcrever vídeos para as suas anotações ou para uma newsletter enxuta, por exemplo). As desvantagens são óbvias: é um ponto único de falha físico, não escala e é uma arquitetura estranha para um produto em produção.

Solução 3: usar cache agressivo e backoff nos erros

Seja qual for o método de busca, duas práticas reduzem muito a taxa de bloqueio. A primeira: faça cache de toda transcrição que você buscar — transcrições quase nunca mudam, então não há motivo para buscar o mesmo vídeo duas vezes. Uma tabela simples no banco, indexada pelo ID do vídeo, elimina a maior parte do tráfego repetido.

A segunda: trate o bloqueio como um sinal, não como um erro para repetir na hora. Backoff exponencial com jitter (espere 1s, depois 2s, 4s, 8s...) mantém você fora do radar. Martelar o endpoint logo depois de um bloqueio é o caminho mais rápido para ter toda a sua faixa de IP banida.

Vale lembrar que isso é mitigação, não solução: em um IP de datacenter, até a sua primeiríssima requisição pode ser bloqueada. Combine com uma das outras três soluções.

Solução 4: usar uma API de transcrição hospedada

A opção gerenciada: deixe que um serviço que já resolveu o problema de IP busque as transcrições por você. O ParseJet expõe um único endpoint — POST /v1/parse/youtube com a URL do vídeo — e devolve a transcrição completa em JSON, junto com o título do vídeo, o canal e a duração. O bloqueio, a gestão de proxies e as mudanças de endpoint ficam do lado do servidor, então o seu código tem três linhas e continua tendo três linhas.

Migrar da youtube-transcript-api leva poucos minutos: troque a chamada da biblioteca por um POST HTTP (funciona em Python, Node.js ou qualquer coisa que fale HTTP — inclusive em funções serverless, justamente onde a abordagem por biblioteca mais costuma ser bloqueada). Peça um idioma de legenda específico com o parâmetro language.

O plano gratuito inclui 300 créditos por mês (uma transcrição do YouTube custa 5 créditos, ou seja, 60 vídeos) e os planos pagos começam em US$ 19/mês. Para a maioria dos produtos, isso sai mais barato do que banda de proxy residencial somada ao tempo de engenharia para ficar cuidando dela.

Qual solução escolher?

Projeto pessoal, volume baixo e conforto técnico: a Solução 2 (máquina residencial) é gratuita e confiável o bastante.

Volume alto com equipe de infraestrutura dedicada: a Solução 1 (proxies residenciais rotativos) dá o maior controle — reserve orçamento para os proxies e para a manutenção contínua.

Aplicação em produção, agente ou pipeline de RAG em que a transcrição é um recurso e não o seu negócio principal: a Solução 4 (API hospedada) — uma chamada HTTP, sem gato e rato. Em todos os casos, some a Solução 3 (cache e backoff) por cima.