Extrae transcripciones de YouTube con curl en 30 segundos

Terminal extrayendo una transcripción de YouTube como texto

No necesitas una cuenta, un SDK ni un navegador headless para convertir un video de YouTube en texto plano. youtube2text.org es una API REST: una llamada para obtener la clave y otra para obtener la transcripción.

Paso 1: Consigue la clave de demostración gratuita

curl -s https://youtube2text.org/api/demo-key

Respuesta:

{"success": true, "apiKey": "yt_..."}

La clave de demostración es compartida y está limitada por IP (5 videos al mes por IP), perfecta para hacer pruebas o para scripts ocasionales.

Paso 2: Obtén una transcripción

curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID&maxChars=5000" \
  -H "x-api-key: yt_YOUR_KEY"

Respuesta exitosa:

{"result": {"videoId": "...", "title": "...", "pubDate": "2025-01-01T00:00:00-07:00",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Eso es todo. Algunos detalles que conviene conocer:

url acepta cualquier formato de YouTube: watch?v=, youtu.be, embed o un id de video de 11 caracteres a secas.
maxChars trunca la transcripción (valor por defecto y máximo: 150000). Muy útil cuando vas a pasar el texto a un LLM con un presupuesto de tokens.
Authorization: Bearer <key> funciona como alternativa a x-api-key.
¿Prefieres POST? Envía JSON: {"url": "...", "maxChars": 5000} al mismo endpoint.

Manejo de errores

Todos los errores llegan con el mismo formato legible por máquina:

{"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "...", "status": 429,
           "docsUrl": "https://youtube2text.org/api.md", "retryAfterSeconds": 3600}}

Los códigos que verás en la práctica:

TRANSCRIPT_UNAVAILABLE — el video no tiene subtítulos de ningún tipo.
RATE_LIMIT_EXCEEDED — cuota agotada; retryAfterSeconds te indica cuándo reintentar.
UNAUTHORIZED — clave ausente o inválida; obtén una en /api/demo-key.

Cuando la clave de demostración se queda corta

Inicia sesión con Google en youtube2text.org/app/keys y crea tu propia clave: la cuenta gratuita también incluye 5 videos al mes, y los planes de pago van desde 50 al mes hasta ilimitado.

La referencia completa legible por máquina — parámetros, todos los códigos de error, integración MCP — está en youtube2text.org/api.md. Si vas a conectar esto a un agente de IA en lugar de a un script de shell, lee a continuación la guía de MCP.