Como obter a transcrição de um vídeo do YouTube com uma API (curl, Python, JavaScript)

Para obter a transcrição de um vídeo do YouTube com uma API, envia um pedido HTTP com o URL ou o ID do vídeo e uma chave de API, e lê a transcrição na resposta. Este guia mostra o pedido em curl, Python e JavaScript com a API de transcrições da sum.video e depois explica os formatos, os erros e o custo.

O que a API devolve

O endpoint devolve as legendas existentes de um vídeo público do YouTube, escritas pelo autor ou geradas automaticamente pelo YouTube. Não transcreve áudio. Se o vídeo não tiver legendas, recebes um erro em vez de um palpite (mais abaixo).

O essencial:

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

A resposta indica a língua real da faixa de legendas e se foi gerada automaticamente, para saberes que qualidade esperar.

Passo 1: cria uma chave de API

Inicia sessão e cria uma chave no painel da API (/dashboard/api no sum.video). Podes ter até 5 chaves ativas, o que ajuda a separar a chave de teste da de produção. A tua primeira chave traz 10 créditos grátis, o suficiente para 5 transcrições, por isso podes experimentar tudo abaixo sem gastar nada.

Passo 2: faz o primeiro pedido

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 o GET também funciona, podes testar a partir de um script que só monte o URL. É melhor enviar a chave no cabeçalho, para não acabar nos registos.

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());
}

Mantém a chave no servidor. Uma chave no código do navegador pode ser copiada por qualquer pessoa que abra as ferramentas de programador.

Passo 3: escolhe o formato certo

Se pensas ligar a um momento do vídeo, usa json e constrói a ligação a partir do offset do segmento. Para dar a um LLM, o text é mais curto e simples. Se mais tarde quiseres pesquisar à mão dentro de uma transcrição, vê como pesquisar na transcrição de um vídeo do YouTube.

Passo 4: escolhe a língua

lang é en por omissão. Define a língua que queres, como de ou es. A resposta indica a língua da faixa realmente devolvida, por isso verifica-a em vez de a assumires. Muitas vezes um vídeo só tem uma faixa de legendas, e a API devolve as legendas reais, por isso não traduz por ti.

Passo 5: trata os erros

Prepara-te desde o primeiro dia para estes casos:

• 404 no_transcript: o vídeo não tem legendas, ou é uma emissão em direto, um vídeo privado ou removido. Não há nada a repetir. Salta-o ou pede outro vídeo ao utilizador.
• 402 budget_exceeded: atingiste o limite mensal de créditos que definiste. Vê a secção seguinte.
• Limite de pedidos: cada chave permite 60 pedidos por minuto. Espaça o trabalho em lote e abranda quando fores limitado.
• Falhas do nosso lado: tenta de novo passado pouco tempo. Não têm custo.

Um ciclo simples que repete em erros de servidor e salta em 404 cobre a maior parte das necessidades de produção.

Quanto custa

Cada transcrição custa 2 créditos. Os pedidos que não devolvem transcrição ou falham do lado da sum.video não custam nada, por isso um 404 nunca esvazia o teu saldo. Podes ver o saldo com GET /api/v1/credits.

Os créditos vendem-se em pacotes únicos que nunca expiram:

Os subscritores Pro recebem ainda 100 créditos de bónus por mês. Para trabalhos pesados, como importar um canal inteiro, lê o cenário transcrições do YouTube para uma app RAG em grande escala, que cobre carregamento automático e orçamentos. Vê também os preços.

Limites a conhecer antes de construir

• Só funcionam vídeos com legendas. É a principal causa de 404 no_transcript.
• As legendas geradas automaticamente podem ter erros, sobretudo em nomes, sotaques e termos técnicos.
• A API devolve só a transcrição. Não cria resumos. Se queres resumo, marcas de tempo e conversa sobre a transcrição, o resumidor de YouTube faz isso, e a ferramenta de transcrição é a versão sem código para um vídeo.
• A API oficial YouTube Data não é um substituto aqui. O método de descarga de legendas exige permissão para editar o vídeo, por isso serve para os teus próprios vídeos (documentação da Google).

Fontes

• YouTube Data API: Captions.download
• API de transcrições da sum.video