Cómo obtener la transcripción de YouTube con una API (curl, Python, JavaScript)

Para obtener la transcripción de YouTube con una API, envía una petición HTTP con la URL o el ID del vídeo y una clave de API, y lee la transcripción en la respuesta. Esta guía muestra la petición en curl, Python y JavaScript con la API de transcripciones de sum.video, y luego cubre formatos, errores y costes.

Qué devuelve la API

El endpoint devuelve los subtítulos existentes de un vídeo público de YouTube, ya sean escritos por el creador o generados automáticamente por YouTube. No transcribe audio. Si un vídeo no tiene subtítulos, recibes un error en lugar de una suposición (más abajo).

Lo básico:

• Endpoint: POST https://sum.video/api/v1/transcript (GET también funciona)
• Autenticación: tu clave en la cabecera X-API-Key, o Authorization: Bearer <key>
• Entrada: url o video_id
• lang opcional (por defecto en)
• format opcional: json, text o srt

La respuesta también indica el idioma real de la pista de subtítulos y si fue generada automáticamente, así sabes qué calidad esperar.

Paso 1: Crea una clave de API

Inicia sesión y crea una clave en el panel de la API (/dashboard/api en sum.video). Puedes tener hasta 5 claves activas, útil para separar una clave de pruebas de una de producción. Tu primera clave viene con 10 créditos gratis, suficientes para 5 transcripciones, así que puedes probar todo lo siguiente sin coste.

Paso 2: Haz tu primera 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 también funciona, puedes probar desde un script que solo construya URLs. Es mejor pasar la clave en la cabecera para que no acabe en los registros.

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

Guarda la clave en un servidor. Una clave en el código del navegador la puede copiar cualquiera que abra las herramientas de desarrollo.

Paso 3: Elige el formato adecuado

Si piensas enlazar a un momento del vídeo, usa json y construye el enlace a partir del offset del segmento. Para alimentar un LLM, text es más pequeño y simple. Si más adelante quieres buscar a mano dentro de una transcripción, mira cómo buscar dentro de la transcripción de un vídeo de YouTube.

Paso 4: Elige un idioma

lang es en por defecto. Ponlo en el idioma que quieras, por ejemplo de o es. La respuesta indica el idioma de la pista que se devolvió realmente, así que compruébalo en lugar de darlo por hecho. Un vídeo suele tener una sola pista de subtítulos, y la API devuelve subtítulos reales, por lo que no los traduce por ti.

Paso 5: Gestiona los errores

Prevé estos casos desde el primer día:

• 404 no_transcript: el vídeo no tiene subtítulos, o es una emisión en directo, un vídeo privado o uno eliminado. No hay nada que reintentar. Sáltalo o pide otro vídeo al usuario.
• 402 budget_exceeded: has alcanzado el límite mensual de créditos que configuraste. Mira la sección siguiente.
• Límite de peticiones: cada clave permite 60 peticiones por minuto. Espacia los trabajos por lotes y retrocede cuando te limiten.
• Fallos por nuestra parte: reintenta con una breve espera. No cuestan nada.

Un bucle sencillo que reintente ante errores del servidor y se salte los 404 cubre la mayoría de las necesidades de producción.

Cuánto cuesta

Cada transcripción cuesta 2 créditos. Las peticiones que no devuelven transcripción o que fallan por parte de sum.video no cuestan nada, así que un 404 nunca consume tu saldo. Puedes consultar tu saldo con GET /api/v1/credits.

Los créditos se venden en paquetes únicos que nunca caducan:

Los suscriptores Pro también reciben 100 créditos de bonificación al mes. Para cargas más pesadas, como ingerir un canal entero, lee el escenario transcripciones de YouTube para una app RAG a gran escala, que trata la recarga automática y los presupuestos. Mira también los precios.

Límites que conviene conocer antes de construir

• Solo funcionan los vídeos con subtítulos. Es la razón principal del 404 no_transcript.
• Los subtítulos generados automáticamente pueden tener errores, sobre todo con nombres, acentos y términos técnicos.
• La API solo devuelve la transcripción. No resume. Si quieres resúmenes, marcas de tiempo y chat sobre una transcripción, lo hace el resumidor de YouTube, y la herramienta de transcripción es la versión sin código para un solo vídeo.
• La API oficial YouTube Data no sustituye a esta. Su método de descarga de subtítulos exige permiso para editar el vídeo, así que está pensado para tus propios vídeos (documentación de Google).

Fuentes

• YouTube Data API: Captions.download
• API de transcripciones de sum.video