Como obter a transcrição do YouTube com uma API (curl, Python, JavaScript)

Para obter a transcrição do YouTube com uma API, envie uma requisição HTTP com a URL ou o ID do vídeo e uma chave de API, e leia a transcrição na resposta. Este guia mostra a requisição em curl, Python e JavaScript com a API de transcrição do sum.video e depois trata de formatos, erros e custos.

O que a API retorna

O endpoint retorna as legendas existentes de um vídeo público do YouTube, escritas pelo criador ou geradas automaticamente pelo YouTube. Ele não transcreve áudio. Se um vídeo não tem legendas, você recebe um erro em vez de um palpite (mais abaixo).

O básico:

• Endpoint: POST https://sum.video/api/v1/transcript (GET também funciona)
• Autenticação: sua chave no cabeçalho X-API-Key, ou Authorization: Bearer <key>
• Entrada: url ou video_id
• lang opcional (padrão en)
• format opcional: json, text ou srt

A resposta também informa o idioma real da faixa de legendas e se ela foi gerada automaticamente, para você saber que qualidade esperar.

Passo 1: Crie uma chave de API

Entre e crie uma chave no painel da API (/dashboard/api no sum.video). Você pode ter até 5 chaves ativas, útil para separar uma chave de teste de uma de produção. Sua primeira chave vem com 10 créditos grátis, o suficiente para 5 transcrições, então você pode testar tudo abaixo sem custo.

Passo 2: Faça sua primeira requisição

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

Como GET também funciona, você pode testar a partir de um script que apenas monta URLs. Prefira o cabeçalho para a chave, para que ela não acabe nos logs.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18+ ou navegador)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

Mantenha a chave em um servidor. Uma chave colocada no código do navegador pode ser copiada por qualquer pessoa que abra as ferramentas de desenvolvedor.

Passo 3: Escolha o formato certo

Se você pretende linkar para um momento do vídeo, use json e monte o link a partir do offset do segmento. Para alimentar um LLM, text é menor e mais simples. Se depois quiser buscar manualmente dentro de uma transcrição, veja como pesquisar dentro da transcrição de um vídeo do YouTube.

Passo 4: Escolha um idioma

lang é en por padrão. Defina o idioma que quiser, por exemplo de ou es. A resposta informa o idioma da faixa que realmente foi retornada, então confira em vez de presumir. Um vídeo muitas vezes tem só uma faixa de legendas, e a API retorna legendas reais, portanto não as traduz para você.

Passo 5: Trate os erros

Planeje estes casos desde o primeiro dia:

• 404 no_transcript: o vídeo não tem legendas, ou é uma transmissão ao vivo, um vídeo privado ou removido. Não há o que tentar de novo. Pule-o ou peça outro vídeo ao usuário.
• 402 budget_exceeded: você atingiu o limite mensal de créditos que configurou. Veja a próxima seção.
• Limite de taxa: cada chave permite 60 requisições por minuto. Espace os trabalhos em lote e reduza o ritmo quando for limitado.
• Falhas do nosso lado: tente de novo após um breve intervalo. Elas não custam nada.

Um laço simples que tenta de novo em erros do servidor e pula os 404 cobre a maior parte das necessidades de produção.

Quanto custa

Cada transcrição custa 2 créditos. Requisições que não retornam transcrição, ou que falham do lado do sum.video, não custam nada, então um 404 nunca consome seu saldo. Você pode ver seu saldo com GET /api/v1/credits.

Os créditos são vendidos em pacotes únicos que nunca expiram:

Assinantes Pro também recebem 100 créditos de bônus por mês. Para cargas maiores, como ingerir um canal inteiro, leia o cenário transcrições do YouTube para um app RAG em grande escala, que trata de recarga automática e orçamentos. Veja também os preços.

Limites que você deve conhecer antes de construir

• Só funcionam vídeos com legendas. Esse é o principal motivo do 404 no_transcript.
• Legendas geradas automaticamente podem ter erros, especialmente com nomes, sotaques e termos técnicos.
• A API retorna apenas a transcrição. Ela não resume. Se você quer resumos, marcações de tempo e chat sobre uma transcrição, o resumidor do YouTube faz isso, e a ferramenta de transcrição é a versão sem código para um único vídeo.
• A API oficial YouTube Data não substitui esta. O método de download de legendas exige permissão para editar o vídeo, então serve para os seus próprios vídeos (documentação do Google).

Fontes

• YouTube Data API: Captions.download
• API de transcrição do sum.video