youtube-transcript-api es una librería gratuita y de código abierto para Python que obtiene los subtítulos de un video de YouTube: pip install youtube-transcript-api y luego YouTubeTranscriptApi().fetch(video_id). Funciona bien desde tu propio ordenador, pero desde un servidor en la nube YouTube suele bloquearla con RequestBlocked o IpBlocked, y no sirve para videos sin subtítulos.
La ejecutamos desde una máquina en la nube el 21 de noviembre de 2026 y después pasamos los mismos dos videos por nuestra propia API alojada desde esa misma máquina. Aquí está lo que hizo cada una, cómo usar la librería y cuándo encaja mejor una API alojada.
¿Qué es youtube-transcript-api?
Es una librería de Python de Jonas Depoix, en GitHub y PyPI, con licencia MIT. La versión actual es la 1.2.5, para Python 3.8 o superior.
- Lee los subtítulos que YouTube ya tiene, los del propio canal o los automáticos de YouTube.
- No necesita clave de API ni navegador headless.
- Puede listar los idiomas de subtítulos de un video, preferir un idioma sobre otro y usar la traducción automática de YouTube.
- Da formato de texto, JSON, SRT o WebVTT, y tiene una herramienta de línea de comandos.
Su README es claro sobre el compromiso: usa una parte no documentada del reproductor web de YouTube, así que no hay "no guarantee that it won't stop working tomorrow".
¿Cómo la uso?
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
Desde la línea de comandos, youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json hace lo mismo. El README explica cómo listar idiomas, la traducción y lo demás.
¿Por qué falla con IpBlocked en mi servidor?
Porque YouTube bloquea la mayoría de las solicitudes de proveedores de nube. El README de la librería lo dice claramente: YouTube "has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)", así que lo "most likely" es que veas errores RequestBlocked o IpBlocked al desplegar tu código. Una IP doméstica también puede bloquearse tras demasiadas solicitudes.
Lo vimos de primera mano. El 21 de noviembre de 2026 instalamos la versión 1.2.5 en una máquina en la nube y pedimos dos clases públicas:
Misma máquina, mismos dos videos, 21 de noviembre de 2026 (UTC).
Las dos llamadas dieron IpBlocked en unos 1,1 segundos. Una solicitud simple a youtube.com desde esa máquina fue redirigida a la página de "tráfico inusual" de Google, así que era YouTube rechazando la máquina, no un fallo de la librería.
La solución del README son los proxies, y recomienda proxies residenciales rotativos, porque YouTube bloquea los proxies estáticos tras un uso prolongado. Funciona, pero significa otro servicio de pago, otra cuenta y bloqueos que vigilar.
¿Qué más puede detenerla?
- Sin subtítulos. La librería lee subtítulos; no transcribe audio. Los subtítulos desactivados dan
TranscriptsDisabled, y un idioma que falta daNoTranscriptFound. - Videos con restricción de edad. El README dice que el inicio de sesión con cookies, que estos necesitan, está "currently not available" tras cambios en YouTube.
- Cambios de YouTube. Como usa una interfaz no documentada, una actualización de YouTube puede romperla hasta que salga una nueva versión.
Nada de esto es motivo para evitarla en un script en tu portátil. Es motivo para tenerlo en cuenta antes de meterla en un producto.
¿Qué puedo usar cuando la bloquean?
Una API de transcripción alojada, que hace la descarga desde su lado. La nuestra es la API de YouTubeTranscript.dev. Desde la misma máquina en la nube, unos minutos antes, los mismos dos videos:
| Video | Duración | Tiempo | Palabras | Líneas con tiempo | Créditos |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4,2 segundos | 3.357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4,2 segundos | 6.363 | 887 | 1 |
| El mismo video de 3Blue1Brown, pedido otra vez | 18:40 | 1,3 segundos | 3.357 | 286 | 0 |
Cómo lo medimos: una solicitud a POST /api/v2/transcribe para cada uno, solo subtítulos y con marcas de tiempo, cronometrada con curl desde el envío hasta la respuesta completa. Los créditos son los que informó cada respuesta. Una prueba por video, así que toma los tiempos como ejemplos.
La llamada desde Python:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
El compromiso es el costo: la librería es gratis y la API cuesta 1 crédito por video con subtítulos, con 10 créditos gratis al mes y planes de pago desde 5 dólares por 500. Con "mode": "auto" también transcribe videos sin subtítulos, a 1 crédito por cada 2 minutos de audio. Hay un SDK de Python si prefieres no escribir la solicitud tú.
¿Cómo integro una API de transcripción en mi producto?
El mismo patrón sirve con cualquier API:
- Guarda la clave en tu servidor. Tus usuarios envían un enlace a tu backend y tu backend llama a la API. Nunca pongas la clave en el código del navegador o de la app.
- Acepta cualquier formato de enlace. Pasa el enlace tal como lo escribió el usuario; la nuestra acepta URL completas, youtu.be, Shorts, embeds e ID sueltos (la lista completa).
- Guarda la transcripción por ID de video. La mayoría de los productos piden los mismos videos populares una y otra vez. Con la nuestra, una transcripción que tu cuenta ya tiene no cuesta nada al pedirla de nuevo, como muestra la tercera fila, pero una copia local es aún más rápida.
- Trata los videos sin subtítulos como un trabajo. Transcribir audio tarda más de lo que debería esperar una solicitud web. Envía
mode: "auto"con unawebhook_url, o consulta el ID de trabajo devuelto, y muestra al usuario el progreso. - Usa lotes cuando tengas muchos. Para una lista, un canal o un acumulado, usa el endpoint de lotes en vez de un bucle de llamadas sueltas, para no pasarte del límite de velocidad.
La documentación de la API tiene todos los campos, y nuestra guía de la API de voz a texto mide precisión y costo con audio sin subtítulos.
¿Cuál debería usar?
| Si estás... | Usa |
|---|---|
| Ejecutando un script en tu ordenador, con pocos videos a la vez | youtube-transcript-api |
| Desplegando en un servidor en la nube, una función serverless o un producto | Una API alojada, o la librería más proxies residenciales rotativos |
| Procesando videos sin subtítulos | Un servicio que transcriba audio |
| Descargando listas o canales completos | Una API alojada con endpoint de lotes |
Resumen
- youtube-transcript-api es gratis, con licencia MIT y fácil:
YouTubeTranscriptApi().fetch(video_id). - En un servidor en la nube YouTube suele bloquearla; en nuestra máquina en la nube los dos videos dieron
IpBlockeden unos 1,1 segundos. La solución que propone son proxies. - Solo lee subtítulos existentes, y los videos con restricción de edad no funcionan por ahora.
- Una API alojada devolvió los mismos videos desde la misma máquina en 4,2 segundos cada uno, por 1 crédito cada uno, y también procesa videos sin subtítulos.
Preguntas frecuentes
¿Qué es youtube-transcript-api?+
Una librería de código abierto para Python (licencia MIT) que obtiene los subtítulos que YouTube ya tiene de un video, también los automáticos, sin clave de API ni navegador. Se instala con pip install youtube-transcript-api y se usa con YouTubeTranscriptApi().fetch(video_id).
¿Por qué youtube-transcript-api da RequestBlocked o IpBlocked?+
Porque YouTube bloquea la mayoría de las solicitudes desde direcciones IP de proveedores de nube, y puede bloquear cualquier IP que haga demasiadas solicitudes. El README de la librería lo dice y sugiere proxies residenciales rotativos. Desde nuestra máquina en la nube, el 21 de noviembre de 2026, los dos videos que probamos dieron IpBlocked en unos 1,1 segundos.
¿Puede youtube-transcript-api transcribir un video sin subtítulos?+
No. Lee subtítulos que ya existen. Un video con subtítulos desactivados da TranscriptsDisabled, y uno sin tu idioma da NoTranscriptFound. Para sacar texto del audio necesitas un servicio de voz a texto.
¿youtube-transcript-api es gratis?+
Sí, la librería es gratuita y con licencia MIT. Usarla en un servidor suele implicar pagar proxies, porque las IP de la nube están bloqueadas.
¿Qué puedo usar en lugar de youtube-transcript-api en un servidor?+
Una API de transcripción alojada que hace la descarga por ti. Desde la misma máquina donde la librería fue bloqueada, la API de YouTubeTranscript.dev devolvió los dos videos en 4,2 segundos cada uno, por 1 crédito cada uno, y una solicitud repetida en 1,3 segundos gratis.
¿Cómo integro una API de transcripción en mi producto?+
Guarda la clave de API en tu servidor, envía el enlace del video a un endpoint, guarda la transcripción por ID de video para no pagar dos veces, trata los videos sin subtítulos como un trabajo asíncrono con webhook y usa un endpoint de lotes para muchos videos a la vez.