YouTube Transcript (Apify)

youtube-transcript-apify

Uma API de transcrição do YouTube para Python que continua funcionando na AWS, Google Cloud, Azure, Vercel, Render e outros servidores em nuvem: uma correção substituta para youtube-transcript-api quando ele é bloqueado por IP.

Se o seu código funciona no seu laptop, mas falha em produção com RequestBlocked, IpBlocked, TooManyRequests ou HTTP 429, o YouTube está bloqueando o endereço IP do seu servidor. A maioria das faixas de IP de nuvem é bloqueada. Este pacote envia a solicitação para um scraper hospedado na Apify que lida com proxies e tentativas, e devolve dados Python simples.

• Mesma estrutura da chamada clássica do youtube-transcript-api: uma lista de {"text", "start", "duration"}.
• Texto simples, texto com carimbo de tempo, legendas SRT e VTT, no idioma original do vídeo, em qualquer idioma de legenda solicitado ou traduzido.
• Vídeos sem legendas são reportados, não cobrados.
• O cliente usa apenas a biblioteca padrão. Inclui uma CLI e um servidor MCP para Claude, Cursor e outros agentes de IA.

Divulgação: este pacote é um cliente leve para o Actor YouTube Transcript Scraper, criado pelo mesmo autor (nokia2k). As execuções são cobradas pela Apify: US$ 2,99 por 1.000 transcrições no plano gratuito da Apify, reduzindo para US$ 1,49 em planos pagos, no momento em que este texto foi escrito. O plano gratuito inclui US$ 5 de crédito todo mês, sem necessidade de cartão.

Instalação

pip install youtube-transcript-apify   # client, CLI and MCP server

Obtenha um token de API gratuito em https://console.apify.com/settings/integrations e configure-o:

export APIFY_TOKEN=apify_api_...

Use a API de transcrição do YouTube em Python

Substitua a chamada que está sendo bloqueada:

# before
# from youtube_transcript_api import YouTubeTranscriptApi
# segments = YouTubeTranscriptApi.get_transcript("arj7oStGLkU", languages=["en"])

# after
from yt_transcript_apify import get_transcript
segments = get_transcript("arj7oStGLkU", languages=["en"])
print(segments[0])   # {'text': 'So in college,', 'start': 1.2, 'duration': 2.16}

Mais controle:

from yt_transcript_apify import ApifyTranscriptClient

client = ApifyTranscriptClient()                  # reads APIFY_TOKEN
t = client.fetch("https://youtu.be/arj7oStGLkU", formats=["text", "srt"])
print(t.title, t.language, t.is_generated)
print(t.text[:200])
open("talk.srt", "w").write(t.srt)

rows = client.fetch_many(["arj7oStGLkU", "iG9CE55wbtY"], translate_to="es")
for row in rows:
    print(row["status"], row.get("title"))       # failed videos keep a plain message

fetch levanta TranscriptError (com .status, por exemplo, no_captions, video_unplayable, video_unavailable) quando um vídeo não tem transcrição. fetch_many nunca levanta exceções para vídeos individuais: cada linha carrega seu próprio status e message.

Carregador de documentos LangChain

pip install "youtube-transcript-apify[langchain]"

from yt_transcript_apify.langchain import YouTubeTranscriptApifyLoader

docs = YouTubeTranscriptApifyLoader(
    ["https://youtu.be/arj7oStGLkU", "iG9CE55wbtY"], languages=["en"]
).load()
print(docs[0].metadata["title"], len(docs[0].page_content))

Um Document por vídeo, com title, channelName, language, durationSeconds e source nos metadados. Vídeos sem legendas são ignorados. Funciona da mesma forma na AWS, GCP ou Vercel, onde o carregador clássico é bloqueado por IP.

Linha de comando

yt-transcript-apify arj7oStGLkU                   # plain text
yt-transcript-apify https://youtu.be/arj7oStGLkU --format srt > talk.srt
yt-transcript-apify arj7oStGLkU --lang es --translate en

Servidor MCP de transcrição do YouTube (Claude Desktop, Claude Code, Cursor)

Adicione isto à configuração do seu cliente MCP:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uvx",
      "args": ["youtube-transcript-apify"],
      "env": { "APIFY_TOKEN": "apify_api_..." }
    }
  }
}

Ferramentas:

Ferramenta	O que faz
get_youtube_transcript	Um vídeo ou Short: text, timestamps, srt ou vtt, idioma e tradução opcionais
get_youtube_transcripts	Até 50 vídeos de uma vez, texto simples, uma seção por vídeo

Depois pergunte: "Resuma este vídeo: https://www.youtube.com/watch?v=arj7oStGLkU".

Outras formas de chamar o mesmo scraper

• Sem código: execute-o na página da Apify Store e baixe JSON, CSV ou Excel.
• n8n, Make, Zapier: use a integração da Apify e escolha nokia2k/youtube-transcript-scraper.
• Milhares de vídeos como texto simples: YouTube Video to Text é mais barato por vídeo.
• Canais inteiros, playlists, resultados de busca, curtidas e comentários: YouTube Scraper.

FAQ

Por que o youtube-transcript-api funciona localmente, mas não no meu servidor? O YouTube bloqueia a maioria das solicitações de faixas de IP de provedores de nuvem. Proxies residenciais rotativos resolvem isso; este pacote usa um serviço hospedado que já os possui, então você não gerencia proxies.

É gratuito? O pacote é gratuito e de código aberto (MIT). As execuções da Apify que ele chama são pagas por transcrição: US$ 2,99 por 1.000 no plano gratuito, cujo crédito mensal de US$ 5 cobre aproximadamente 1.600 transcrições.

Como corrijo RequestBlocked ou IpBlocked do youtube-transcript-api? Substitua YouTubeTranscriptApi.get_transcript por yt_transcript_apify.get_transcript (veja acima). A solicitação então sai dos proxies da Apify em vez do IP bloqueado do seu servidor, e o resultado tem a mesma estrutura.

Posso baixar legendas do YouTube como SRT ou VTT? Sim: client.fetch(video, formats=["srt", "vtt"]) retorna ambos, ou use --format srt na linha de comando.

Quais dados ele retorna? Apenas o que o YouTube mostra publicamente: legendas, título, canal, idioma. Ele não baixa vídeo ou áudio.

Licença

MIT