API de Transcrições do YouTube não funciona? Checklist de diagnóstico

Checklist de diagnóstico

Compare seu código de erro (ou o formato da sua resposta) com a tabela abaixo.

Bloqueado na AWS, GCP, Azure ou uma VPS?

Se um script funciona perfeitamente no seu notebook e falha assim que é implantado em um servidor na nuvem, quase sempre é por isso: o endpoint de legendas do YouTube bloqueia faixas inteiras de IPs de datacenter, não apenas IPs individuais abusivos. O espaço de IPs de todo grande provedor de nuvem acaba sendo afetado, porque milhares de scripts sem relação entre si compartilham as mesmas faixas de endereços.

Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.

Formas realistas de contornar isso, mais ou menos em ordem de esforço:

• Rotear requisições por um pool de proxies residenciais ou móveis - funciona às vezes, mas relatos de que até configurações residenciais rotativas pagas continuam falhando são cada vez mais comuns. Não é uma correção permanente.
• Alternar entre vários provedores de nuvem ou regiões - ganha tempo até essas faixas também serem sinalizadas.
• Fazer cache agressivamente para não buscar os mesmos vídeos de novo - reduz a frequência do bloqueio, não o elimina.
• Usar uma API hospedada que já mantém essa infraestrutura - o problema deixa de ser 'seu projeto' e passa a ser 'alguém cujo trabalho real é manter isso funcionando'.

Essa é a lacuna real que nossa própria API de Transcrições do YouTube preenche - não uma biblioteca diferente, mas infraestrutura já construída especificamente para esse problema.

Está recebendo PoTokenRequired?

Uma falha mais recente: o endpoint de legendas do YouTube cada vez mais exige um token de origem gerado em tempo de execução pelo próprio JavaScript do player - não um cookie, não uma verificação de reputação de IP, um valor criptográfico. Uma requisição HTTP simples não tem como gerar isso.

Veja o detalhe técnico real em jdepoix/youtube-transcript-api#592 - segundo esse relato, não existe solução documentada na biblioteca open-source.

Esse é exatamente o tipo de problema que uma API hospedada deve absorver - chame um endpoint e receba uma transcrição ou um erro claro, sem precisar resolver a geração do token você mesmo.

O que nossa própria API retorna para cada falha

Se você já usa nossa API e quer tratar a falha exata em vez de adivinhar só pelo status HTTP, todo erro vem com um campo `code` estável:

curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer sk_live_..."

# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }

A referência completa de parâmetros e todos os códigos de status estão na documentação da API.