YOUTUBE TRANSCRIPT API · GUIA

Como usar o youtube-transcript-api em Python, e por que ele falha no meu servidor?

O youtube-transcript-api é uma biblioteca Python gratuita e de código aberto: instale com pip e chame fetch() com o ID do vídeo. Funciona bem no seu computador, mas em um servidor na nuvem o YouTube costuma bloqueá-la. Rodamos a partir de um em 21 de novembro de 2026 e recebemos IpBlocked nos dois vídeos.

Atualizado em 21 de novembro de 2026 · 5 min de leitura

O youtube-transcript-api é uma biblioteca Python gratuita e de código aberto que busca as legendas de um vídeo do YouTube: pip install youtube-transcript-api e depois YouTubeTranscriptApi().fetch(video_id). Funciona bem no seu próprio computador, mas a partir de um servidor na nuvem o YouTube costuma bloqueá-la com RequestBlocked ou IpBlocked, e ela não ajuda com vídeos sem legendas.

Rodamos a biblioteca em uma máquina na nuvem em 21 de novembro de 2026 e depois passamos os mesmos dois vídeos pela nossa própria API hospedada, da mesma máquina. Aqui está o que cada uma fez, como usar a biblioteca e quando uma API hospedada é a melhor opção.

O que é o youtube-transcript-api?

É uma biblioteca Python de Jonas Depoix, no GitHub e no PyPI, com licença MIT. A versão atual é a 1.2.5, para Python 3.8 ou superior.

  • Lê as legendas que o YouTube já tem, as do próprio canal ou as automáticas do YouTube.
  • Não precisa de chave de API nem de navegador headless.
  • Lista os idiomas de legenda de um vídeo, prefere um idioma a outro e usa a tradução automática do YouTube.
  • Formata a saída em texto, JSON, SRT ou WebVTT e tem uma ferramenta de linha de comando.

O README é franco sobre a troca: ela usa uma parte não documentada do player web do YouTube, então há "no guarantee that it won't stop working tomorrow".

Como usar?

pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter

ytt_api = YouTubeTranscriptApi()

# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])

for snippet in transcript:
    print(snippet.start, snippet.text)

print(SRTFormatter().format_transcript(transcript))

Na linha de comando, youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json faz o mesmo. O README explica como listar idiomas, traduzir e o resto.

Por que falha com IpBlocked no meu servidor?

Porque o YouTube bloqueia a maioria das solicitações de provedores de nuvem. O README da biblioteca diz isso com clareza: o YouTube "has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)", então você vai "most likely" encontrar erros RequestBlocked ou IpBlocked depois de publicar o código. Um IP doméstico também pode ser bloqueado após solicitações demais.

Vimos isso na prática. Em 21 de novembro de 2026 instalamos a versão 1.2.5 em uma máquina na nuvem e pedimos duas aulas públicas:

youtube-transcript-api dando IpBlocked em uma máquina na nuvem, e os mesmos dois vídeos devolvidos pela API do YouTubeTranscript.dev a partir da mesma máquinaMesma máquina, mesmos dois vídeos, 21 de novembro de 2026 (UTC).

As duas chamadas deram IpBlocked em cerca de 1,1 segundo. Uma solicitação simples para youtube.com a partir dessa máquina foi redirecionada para a página de "tráfego incomum" do Google, então era o YouTube recusando a máquina, não um erro da biblioteca.

A solução do README são proxies, e ele recomenda proxies residenciais rotativos, porque o YouTube bane proxies estáticos após uso prolongado. Funciona, mas significa mais um serviço pago, mais uma conta e bloqueios para acompanhar.

O que mais pode impedir?

  • Sem legendas. A biblioteca lê legendas; não transcreve áudio. Legendas desativadas geram TranscriptsDisabled, e um idioma ausente gera NoTranscriptFound.
  • Vídeos com restrição de idade. O README diz que o login por cookies, que esses vídeos exigem, está "currently not available" depois de mudanças no YouTube.
  • Mudanças do YouTube. Como usa uma interface não documentada, uma atualização do YouTube pode quebrá-la até sair uma nova versão.

Nada disso é motivo para evitá-la em um script no seu notebook. É motivo para se planejar antes de colocá-la em um produto.

O que usar quando ela é bloqueada?

Uma API de transcrição hospedada, que faz a busca do lado dela. A nossa é a API do YouTubeTranscript.dev. Da mesma máquina na nuvem, alguns minutos antes, os mesmos dois vídeos:

VídeoDuraçãoTempoPalavrasLinhas com tempoCréditos
But what is a neural network? (3Blue1Brown)18:404,2 segundos3.3572861
1. What is Computation? (MIT OpenCourseWare)43:064,2 segundos6.3638871
O mesmo vídeo do 3Blue1Brown, pedido de novo18:401,3 segundo3.3572860

Como medimos: uma solicitação a POST /api/v2/transcribe para cada um, só legendas e com marcação de tempo, cronometrada pelo curl do envio até a resposta completa. Os créditos são os informados por cada resposta. Um teste cada, então trate os tempos como exemplos.

A chamada em Python:

import requests

r = requests.post(
    "https://www.youtubetranscript.dev/api/v2/transcribe",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
    print(seg["start"], seg["text"])  # start and end are in milliseconds

A troca é o custo: a biblioteca é grátis, e a API custa 1 crédito por vídeo com legendas, com 10 créditos grátis por mês e planos pagos a partir de US$ 5 por 500. Com "mode": "auto" ela também transcreve vídeos sem legendas, a 1 crédito a cada 2 minutos de áudio. Há um SDK para Python se preferir não escrever a solicitação.

Como integro uma API de transcrição no meu produto?

O mesmo padrão funciona com qualquer API:

  1. Mantenha a chave no servidor. Seus usuários mandam um link para o seu backend, e o backend chama a API. Nunca coloque a chave no código do navegador ou do app.
  2. Aceite qualquer formato de link. Repasse o link como o usuário digitou; a nossa aceita URLs completas, youtu.be, Shorts, embeds e IDs soltos (a lista completa).
  3. Guarde a transcrição pelo ID do vídeo. A maioria dos produtos pede os mesmos vídeos populares várias vezes. Com a nossa, uma transcrição que sua conta já tem não custa nada para buscar de novo, como mostra a terceira linha, mas uma cópia local é ainda mais rápida.
  4. Trate vídeos sem legendas como um trabalho. Transcrever áudio leva mais tempo do que uma solicitação web deveria esperar. Envie mode: "auto" com uma webhook_url, ou consulte o ID do trabalho devolvido, e mostre o progresso ao usuário.
  5. Use lotes quando forem muitos. Para uma playlist, um canal ou um acúmulo, use o endpoint de lote em vez de um loop de chamadas, para ficar dentro do limite de taxa.

A documentação da API tem todos os campos, e o nosso guia da API de fala para texto mede precisão e custo em áudio sem legendas.

Qual devo usar?

Se você está...Use
Rodando um script no seu computador, poucos vídeos por vezyoutube-transcript-api
Publicando em um servidor na nuvem, uma função serverless ou um produtoUma API hospedada, ou a biblioteca com proxies residenciais rotativos
Lidando com vídeos sem legendasUm serviço que transcreva áudio
Buscando playlists ou canais inteirosUma API hospedada com endpoint de lote

Resumo

  • O youtube-transcript-api é grátis, tem licença MIT e é simples: YouTubeTranscriptApi().fetch(video_id).
  • Em um servidor na nuvem o YouTube costuma bloqueá-lo; na nossa máquina na nuvem os dois vídeos deram IpBlocked em cerca de 1,1 segundo. A solução sugerida são proxies.
  • Ele só lê legendas existentes, e vídeos com restrição de idade não funcionam por enquanto.
  • Uma API hospedada devolveu os mesmos vídeos da mesma máquina em 4,2 segundos cada, por 1 crédito cada, e também processa vídeos sem legendas.

Perguntas frequentes

O que é o youtube-transcript-api?+

Uma biblioteca Python de código aberto (licença MIT) que busca as legendas que o YouTube já tem para um vídeo, inclusive as automáticas, sem chave de API e sem navegador. Instale com pip install youtube-transcript-api e chame YouTubeTranscriptApi().fetch(video_id).

Por que o youtube-transcript-api dá RequestBlocked ou IpBlocked?+

Porque o YouTube bloqueia a maioria das solicitações de endereços IP de provedores de nuvem e pode bloquear qualquer IP que faça solicitações demais. O README da biblioteca diz isso e sugere proxies residenciais rotativos. Da nossa máquina na nuvem, em 21 de novembro de 2026, os dois vídeos testados deram IpBlocked em cerca de 1,1 segundo.

O youtube-transcript-api transcreve vídeos sem legendas?+

Não. Ele lê legendas que já existem. Um vídeo com legendas desativadas gera TranscriptsDisabled, e um sem o seu idioma gera NoTranscriptFound. Para obter texto a partir do áudio, você precisa de um serviço de fala para texto.

O youtube-transcript-api é grátis?+

Sim, a biblioteca é gratuita e tem licença MIT. Usá-la em um servidor costuma exigir pagar proxies, porque IPs de nuvem são bloqueados.

O que posso usar no lugar do youtube-transcript-api em um servidor?+

Uma API de transcrição hospedada que faz a busca por você. Da mesma máquina em que a biblioteca foi bloqueada, a API do YouTubeTranscript.dev devolveu os dois vídeos em 4,2 segundos cada, por 1 crédito cada, e uma solicitação repetida em 1,3 segundo sem custo.

Como integro uma API de transcrição no meu produto?+

Mantenha a chave da API no seu servidor, envie o link do vídeo para um endpoint, guarde a transcrição pelo ID do vídeo para nunca pagar duas vezes, trate vídeos sem legendas como um trabalho assíncrono com webhook e use um endpoint de lote para muitos vídeos de uma vez.

Continue lendo

Comece já a extrair transcrições gratuitamente

Converta qualquer vídeo do YouTube em texto em segundos. Não é necessário cartão de crédito.

EXPERIMENTE YOUTUBETRANSCRIPT.DEV →
youtube-transcript-api (Python): como usar e por que falha | Creator Research