Como obter a transcrición de YouTube cunha API (curl, Python, JavaScript)

Para obter a transcrición de YouTube cunha API, envía unha petición HTTP co URL ou o ID do vídeo e unha clave de API, e le a transcrición na resposta. Esta guía mostra a petición en curl, Python e JavaScript coa API de transcricións de sum.video, e despois trata formatos, erros e custos.

Que devolve a API

O punto final devolve os subtítulos existentes dun vídeo público de YouTube, escritos polo creador ou xerados automaticamente por YouTube. Non transcribe audio. Se un vídeo non ten subtítulos, recibes un erro en lugar dunha suposición (máis abaixo).

O básico:

• Punto final: POST https://sum.video/api/v1/transcript (GET tamén funciona)
• Autenticación: a túa clave na cabeceira X-API-Key, ou Authorization: Bearer <key>
• Entrada: url ou video_id
• lang opcional (por defecto en)
• format opcional: json, text ou srt

A resposta tamén indica o idioma real da pista de subtítulos e se foi xerada automaticamente, de modo que sabes que calidade esperar.

Paso 1: Crea unha clave de API

Inicia sesión e crea unha clave no panel da API (/dashboard/api en sum.video). Podes ter ata 5 claves activas, útil para separar unha clave de probas dunha de produción. A túa primeira clave vén con 10 créditos gratuítos, abondo para 5 transcricións, así que podes probar todo o que segue sen custo.

Paso 2: Fai a túa primeira petición

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 tamén funciona, podes probar desde un script que só constrúa URL. É mellor pasar a clave na cabeceira para que non acabe nos rexistros.

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

Garda a clave nun servidor. Unha clave no código do navegador pode copiala calquera persoa que abra as ferramentas de desenvolvemento.

Paso 3: Escolle o formato axeitado

Se pensas ligar a un momento do vídeo, usa json e constrúe a ligazón a partir do offset do segmento. Para alimentar un LLM, text é máis pequeno e sinxelo. Se máis adiante queres buscar a man dentro dunha transcrición, mira como buscar dentro da transcrición dun vídeo de YouTube.

Paso 4: Escolle un idioma

lang é en por defecto. Pon o idioma que queiras, por exemplo de ou es. A resposta indica o idioma da pista que realmente se devolveu, así que comproba o idioma en lugar de supoñelo. Un vídeo adoita ter só unha pista de subtítulos, e a API devolve subtítulos reais, polo que non os traduce por ti.

Paso 5: Xestiona os erros

Prevé estes casos dende o primeiro día:

• 404 no_transcript: o vídeo non ten subtítulos, ou é unha emisión en directo, un vídeo privado ou un vídeo eliminado. Non hai nada que reintentar. Sáltao, ou pídelle outro vídeo ao usuario.
• 402 budget_exceeded: chegaches ao límite mensual de créditos que configuraches. Mira a sección seguinte.
• Límite de frecuencia: cada clave permite 60 peticións por minuto. Espaza as tarefas por lotes e baixa o ritmo cando te limiten.
• Erros da nosa parte: reintenta tras unha breve espera. Non custan nada.

Un bucle sinxelo que reintente ante erros do servidor e salte os 404 cobre a maioría das necesidades de produción.

Canto custa

Cada transcrición custa 2 créditos. As peticións que non devolven ningunha transcrición ou que fallan por parte de sum.video non custan nada, de xeito que un 404 nunca che baleira o saldo. Podes consultar o saldo con GET /api/v1/credits.

Os créditos véndense en paquetes únicos que nunca caducan:

Os subscritores de Pro tamén reciben 100 créditos de bonificación cada mes. Para cargas máis pesadas, como ingerir un canle enteiro, le o escenario transcricións de YouTube para unha app RAG a gran escala, que trata a recarga automática e os orzamentos. Mira tamén os prezos.

Límites que convén coñecer antes de construír

• Só funcionan os vídeos con subtítulos. É o motivo principal do 404 no_transcript.
• Os subtítulos xerados automaticamente poden ter erros, sobre todo con nomes, acentos e termos técnicos.
• A API só devolve a transcrición. Non resume. Se queres resumos, marcas de tempo e chat sobre unha transcrición, iso faino o resumidor de YouTube, e a ferramenta de transcrición é a versión sen código para un só vídeo.
• A API oficial de YouTube Data non é un substituto aquí. O seu método de descarga de subtítulos esixe permiso para editar o vídeo, así que está pensado para os teus propios vídeos (documentación de Google).

Fontes

• YouTube Data API: Captions.download
• API de transcricións de sum.video