Los subtítulos son una parte indispensable de la experiencia mediática moderna. Superan las barreras lingüísticas, mejoran la accesibilidad para las personas con problemas de audición y ayudan a los estudiantes de idiomas de todo el mundo. En el corazón de la accesibilidad de los subtítulos se encuentra OpenSubtitles, uno de los repositorios en línea más grandes y populares de archivos de subtítulos. Pero OpenSubtitles es más que un simple sitio web; ofrece una potente API REST que permite a los desarrolladores integrar su vasta base de datos de subtítulos directamente en sus aplicaciones.
Tanto si estás creando un reproductor multimedia, un sistema de gestión de contenidos, una herramienta de aprendizaje de idiomas o cualquier aplicación que pueda beneficiarse de la integración de subtítulos, la API de OpenSubtitles proporciona las herramientas necesarias. Esta completa guía te guiará a través de todo lo que necesitas saber para utilizar eficazmente la API de OpenSubtitles, desde la configuración inicial y la autenticación hasta la búsqueda, descarga, traducción de subtítulos y el cumplimiento de las mejores prácticas.
¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje en conjunto con la máxima productividad?
¡Apidog ofrece todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
¿Qué es la API de OpenSubtitles?
La API de OpenSubtitles es un conjunto de interfaces de programación que permite a los desarrolladores interactuar mediante programación con la base de datos de OpenSubtitles. En lugar de buscar y descargar manualmente subtítulos del sitio web, las aplicaciones pueden utilizar la API para realizar estas acciones automáticamente. Esto abre un mundo de posibilidades para crear experiencias de usuario fluidas y ricas en funciones.
Capacidades clave:
Búsqueda: Encuentra subtítulos basados en varios criterios como el título de la película/serie, el ID de IMDB, el ID de TMDB, el hash del archivo, el idioma y más. Descarga: Recupera archivos de subtítulos específicos identificados a través de los resultados de búsqueda. Traducción con IA: Aprovecha la inteligencia artificial para traducir los subtítulos existentes a diferentes idiomas. Recuperación de información: Accede a metadatos sobre subtítulos y medios.
Primeros pasos: Tus primeros pasos
Antes de que puedas realizar llamadas a la API, hay algunos requisitos previos y conceptos fundamentales que debes comprender.
1. Endpoint de la API:
Todas las interacciones con la API REST de OpenSubtitles se realizan a través de una única URL base:
https://api.opensubtitles.com/api/v1
Todos los endpoints específicos (como buscar o descargar) se añaden a esta URL base.
2. Registro y clave de API:
El acceso a la API requiere autenticación. El método principal implica el uso de una clave de API.
Registrarse: Primero necesitas una cuenta en OpenSubtitles. Si no tienes una, regístrate en su sitio web. Obtener clave de API: Una vez registrado, deberás generar una clave de API. Esto se hace normalmente a través de tu perfil de usuario o una sección de desarrollador dedicada en el sitio web de OpenSubtitles. Mantén tu clave de API segura, ya que identifica las solicitudes de tu aplicación.
3. Autenticación:
La API admite dos métodos de autenticación principales:
Clave de API: El método más sencillo. Incluye tu clave de API en el encabezado Api-Key de cada solicitud. Api-Key: YOUR_API_KEY Token JWT: Para acceder potencialmente a más funciones específicas del usuario o a diferentes límites de velocidad (dependiendo del diseño de la API), puedes iniciar sesión a través del endpoint /login (que se tratará más adelante) para obtener un JSON Web Token (JWT). Este token se incluye entonces en el encabezado Authorization como un token Bearer. Authorization: Bearer YOUR_JWT_TOKEN
Por lo general, todavía necesitas proporcionar el encabezado Api-Key incluso cuando utilizas un token JWT para la identificación de la aplicación.
4. Encabezados esenciales:
Además de los encabezados de autenticación, cada solicitud de API debe incluir:
Content-Type: Para las solicitudes con un cuerpo (como las solicitudes POST), esto debería ser normalmente application/json. Content-Type: application/json **User-Agent:** Esto es crucial. La API requiere una cadena User-Agent descriptiva que identifique tu aplicación. Los User-Agents vagos o predeterminados (como python-requests) podrían ser bloqueados. Un buen formato es YourAppName v1.0. User-Agent: MySubtitleApp v1.2.3
5. Limitación de velocidad:
Como la mayoría de las API públicas, OpenSubtitles aplica límites de velocidad para garantizar un uso justo y la estabilidad del servidor. Exceder estos límites resultará en respuestas de error (a menudo 429 Too Many Requests). Presta mucha atención a los siguientes encabezados de respuesta para gestionar tu tasa de solicitudes:
X-RateLimit-Limit: El número máximo de solicitudes permitidas en la ventana actual. X-RateLimit-Remaining: El número de solicitudes restantes en la ventana actual. X-RateLimit-Reset: La marca de tiempo (a menudo tiempo de época de Unix) cuando se restablece la ventana de límite de velocidad. Retry-After: Si recibes un error 429, este encabezado indica cuántos segundos debes esperar antes de volver a intentarlo.
Implementar lógica en tu aplicación para respetar estos encabezados es esencial para un funcionamiento fiable.
Análisis profundo de la autenticación: El endpoint /login
Si bien el uso de solo la clave de API suele ser suficiente, el endpoint /login permite que tu aplicación se autentique como un usuario específico de OpenSubtitles, obteniendo un JWT.
Endpoint: POST /login
Propósito: Intercambiar credenciales de usuario (nombre de usuario/contraseña) por un token de autenticación JWT.
Cuerpo de la solicitud:
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
Encabezados:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Respuesta exitosa (Ejemplo):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Este es el JWT
"status": 200
}
Usando el JWT:
Una vez obtenido, incluye este valor de token en el encabezado Authorization para las solicitudes posteriores:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
El uso de JWT podría otorgar acceso a cuotas de descarga específicas del usuario u otras funciones vinculadas al nivel de cuenta o al estado VIP del usuario. Recuerda que los JWT suelen tener un tiempo de caducidad, por lo que es posible que debas volver a autenticarte periódicamente.
Funcionalidad principal: Búsqueda de subtítulos (/subtitles)
Este es quizás el endpoint más utilizado. Te permite consultar la vasta base de datos de OpenSubtitles.
Endpoint: GET /subtitles
Propósito: Encontrar subtítulos basados en varios criterios de búsqueda.
Autenticación: Requiere el encabezado Api-Key (y opcionalmente Authorization: Bearer <token>).
Parámetros de consulta clave:
El poder de la búsqueda reside en sus parámetros de consulta flexibles. Puedes combinarlos según sea necesario:
query=<string>: Busca por título de película o episodio (por ejemplo, query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Busca utilizando el ID de IMDb (por ejemplo, imdb_id=tt0133093). Esto suele ser más preciso que query. tmdb_id=<integer>: Busca utilizando el ID de The Movie Database (TMDb) (por ejemplo, tmdb_id=603). También muy preciso. parent_tmdb_id=<integer>: Para buscar episodios, utiliza el ID de TMDb de la serie (por ejemplo, parent_tmdb_id=1399 para Game of Thrones). season_number=<integer>: Combina con parent_tmdb_id (o imdb_id de la serie) para encontrar subtítulos para una temporada específica. episode_number=<integer>: Combina con parent_tmdb_id (o imdb_id de la serie) y season_number para un episodio específico. languages=<string>: Filtra por códigos de idioma (separados por comas, por ejemplo, languages=en,es, languages=fr). Utiliza códigos ISO 639-2B (como eng, spa, fre). moviehash=<string>: Busca utilizando un hash único calculado a partir del archivo de vídeo. Esto proporciona la coincidencia más precisa si tienes el archivo de vídeo en sí. Calcular este hash suele requerir bibliotecas o herramientas específicas. type=<string>: Filtra por tipo (movie o episode). hearing_impaired=<include|exclude|only>: Filtra los subtítulos diseñados para personas con problemas de audición. machine_translated=<include|exclude|only>: Filtra en función de si los subtítulos fueron traducidos automáticamente. ai_translated=<include|exclude|only>: Filtra en función de si los subtítulos fueron traducidos utilizando la función de IA de la API. order_by=<field>: Ordena los resultados (por ejemplo, order_by=download_count). order_direction=<asc|desc>: Especifica la dirección de ordenación.
Ejemplo de solicitud de búsqueda (Búsqueda de subtítulos en inglés para "Inception" a través del ID de TMDb):
GET /api/v1/subtitles?tmdb_id=27205&languages=en HTTP/1.1
Host: api.opensubtitles.com
Api-Key: YOUR_API_KEY
User-Agent: MySubtitleApp v1.0
Accept: application/json
Interpretación de los resultados de búsqueda:
La respuesta es un objeto JSON que contiene una matriz data. Cada elemento de la matriz representa una coincidencia de subtítulos.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // ID del subtítulo (útil pero no para la descarga)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // ID heredado
"language": "en",
"download_count": 500000,
"new_download_count": 150000,
"hearing_impaired": false,
"hd": true,
"format": "srt",
"fps": 23.976,
"votes": 120,
"points": 10,
"ratings": 8.5,
"from_trusted": true,
"foreign_parts_only": false,
"ai_translated": false,
"machine_translated": false,
"upload_date": "2010-10-25T12:00:00Z",
"release": "Inception.2010.720p.BluRay.x264-REWARD",
"comments": "Sync and Corrected by ...",
"legacy_subtitle_id": 987654,
"uploader": {
"uploader_id": 54321,
"name": "UploaderName",
"rank": "Administrator"
},
"feature_details": { // Información sobre la película/episodio
"feature_id": 5555,
"feature_type": "Movie",
"year": 2010,
"title": "Inception",
"movie_name": "Inception",
"imdb_id": "tt1375666",
"tmdb_id": 27205
},
"url": "<https://www.opensubtitles.org/en/subtitles/1234567/inception-en>",
"related_links": [
// ... enlaces a contenido relacionado ...
],
"files": [ // CRUCIAL: Esta matriz contiene los archivos para esta entrada de subtítulo
{
"file_id": 998877, // <<< Este es el ID necesario para el endpoint /download
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Potencialmente más archivos si es un subtítulo de varias partes (por ejemplo, CD1, CD2)
]
}
},
// ... más resultados de subtítulos ...
]
}
La información más importante necesaria para la descarga es el file_id que se encuentra dentro de la matriz attributes.files. Ten en cuenta que una sola entrada de subtítulo (elemento de la matriz data) puede contener varios archivos (por ejemplo, para versiones antiguas de CD1/CD2). Tu aplicación normalmente debería seleccionar el file_id apropiado en función de criterios como cd_number o file_name.
Funcionalidad principal: Descarga de subtítulos (/download)
Una vez que hayas identificado el archivo de subtítulos deseado utilizando el endpoint /subtitles y hayas extraído su file_id, puedes utilizar el endpoint /download para obtener un enlace temporal al archivo de subtítulos real.
Endpoint: POST /download
Propósito: Solicitar un enlace de descarga para un archivo de subtítulos específico.
Autenticación: Requiere el encabezado Api-Key y una autenticación de usuario válida (ya sea un token JWT con sesión iniciada en el encabezado Authorization o potencialmente permisos específicos de la clave de API, dependiendo de la política de la API; a menudo se prefiere/requiere JWT para las descargas para realizar un seguimiento de las cuotas).
Cuerpo de la solicitud:
{
"file_id": 998877 // El file_id obtenido de los resultados de búsqueda
// Parámetros opcionales como "sub_format", "file_name", "in_fps", "out_fps" podrían estar disponibles para la conversión sobre la marcha
}
Encabezados:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Probablemente requerido) User-Agent: YourAppName v1.0
Respuesta exitosa (Ejemplo):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // URL de descarga temporal
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // ¿Número de solicitudes disponibles para este enlace/archivo específico? (Consultar la documentación)
"remaining": 95, // Cuota de descarga restante del usuario para el día/período
"message": "Download count successful.",
"reset_time": "2023-10-27T12:00:00Z", // Cuándo podría restablecerse la cuota de descarga
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Manejo de la descarga:
Realiza la solicitud POST a /download con el file_id correcto. Comprueba el código de estado de la respuesta para ver si la operación se ha realizado correctamente (por ejemplo, 200 OK). Extrae el valor de link de la respuesta JSON. Realiza una solicitud HTTP GET estándar a esta URL de link. Esta solicitud no suele requerir la clave de API ni los encabezados de autorización, ya que el enlace en sí está preautorizado. La respuesta a la solicitud GET en la URL de link será el contenido real del archivo de subtítulos (por ejemplo, el texto del archivo SRT). Guarda este contenido en un archivo (por ejemplo, utilizando el file_name proporcionado).
Importante: Los enlaces de descarga (link) suelen ser temporales y pueden caducar después de un breve período o un cierto número de usos. No almacenes estos enlaces para un uso a largo plazo; obtén un enlace nuevo a través del endpoint /download cada vez que sea necesaria una descarga. Además, supervisa el recuento de descargas remaining para evitar agotar la cuota del usuario.
Funciones avanzadas: Traducción con IA (/ai-translation)
Una adición más reciente al conjunto de herramientas de OpenSubtitles es la función de traducción con tecnología de IA.
Endpoint: POST /ai-translation (o similar, consulta el endpoint exacto en la documentación)
Propósito: Traducir un archivo de subtítulos existente a otro idioma utilizando modelos de IA.
Cómo funciona (conceptual):
Es probable que proporciones el file_id del subtítulo de origen que deseas traducir. Especificas el target_language (por ejemplo, target_language=de para alemán). La API procesa la solicitud, potencialmente poniendo en cola el trabajo de traducción. La respuesta podría indicar el estado del trabajo o proporcionar un nuevo file_id o enlace de descarga para el subtítulo traducido una vez completado.
Casos de uso:
Poner los subtítulos a disposición en idiomas que no estaban originalmente presentes en la base de datos. Proporcionar a los usuarios opciones de traducción a petición dentro de tu aplicación.
Consideraciones:
Las traducciones de IA pueden tener costes asociados o límites/cuotas de velocidad específicos, potencialmente vinculados a niveles VIP o de suscripción. La calidad de la traducción de IA puede variar dependiendo del par de idiomas y la complejidad del texto de origen. Esta función podría requerir permisos de usuario o niveles de suscripción específicos. Consulta la documentación de la API para obtener detalles sobre el uso, los parámetros y las limitaciones.
Mejores prácticas para la integración de la API
Para garantizar que tu aplicación interactúe de forma fluida y responsable con la API de OpenSubtitles, sigue estas mejores prácticas:
Almacena en caché las respuestas: Especialmente para los resultados de búsqueda (/subtitles) que no cambian rápidamente. Si un usuario busca la misma película/episodio varias veces, sirve el resultado almacenado en caché en lugar de acceder a la API repetidamente. Implementa un almacenamiento en caché inteligente con tiempos de caducidad razonables. Respeta los límites de velocidad: Supervisa activamente los encabezados X-RateLimit-* y Retry-After. Implementa estrategias de retroceso exponencial si alcanzas el límite (espera más después de una limitación de velocidad repetida). No sondeos agresivamente la API. Utiliza identificadores específicos: Siempre que sea posible, busca utilizando imdb_id o tmdb_id en lugar de query. Estos proporcionan resultados mucho más precisos y reducen la ambigüedad. Utiliza moviehash para obtener la máxima precisión si el archivo de vídeo está disponible. Proporciona un User-Agent claro: Utiliza una cadena User-Agent única y descriptiva (por ejemplo, MyMediaPlayerApp/2.1 (contact@myapp.com)). Esto ayuda a OpenSubtitles a identificar las fuentes de tráfico y solucionar problemas. Los agentes genéricos pueden ser bloqueados. Maneja los errores con elegancia: Comprueba los códigos de estado HTTP para cada respuesta. Implementa lógica para manejar errores comunes como 401 Unauthorized (clave de API/JWT no válida), 403 Forbidden (permiso denegado), 404 Not Found, 429 Too Many Requests y errores del servidor 5xx. Proporciona información informativa al usuario. Gestiona las cuotas de descarga: Ten en cuenta los límites de descarga diarios/periódicos asociados con la cuenta del usuario (o la clave de API). Informa a los usuarios si se están acercando o han superado su cuota. Utiliza el campo remaining en la respuesta /download. Optimiza las búsquedas: No solicites datos innecesarios. Utiliza parámetros como languages, type, hearing_impaired, etc., para reducir los resultados del lado del servidor en lugar de filtrar grandes conjuntos de datos del lado del cliente. Protege tu clave de API: Trata tu clave de API como una contraseña. No la incrustes directamente en el código del lado del cliente. Almacénala de forma segura en tu servidor.
Wrappers, scripts y recursos de la comunidad
Si bien esta guía cubre la interacción directa con la API, el ecosistema de OpenSubtitles a menudo incluye recursos desarrollados por la comunidad.
Wrappers de API: Busca bibliotecas o SDK para tu lenguaje de programación (por ejemplo, Python, JavaScript, Java) en plataformas como GitHub o administradores de paquetes (PyPI, npm). Estos wrappers pueden simplificar las llamadas a la API, manejar la autenticación y analizar las respuestas. Scripts: Pueden existir varias herramientas o scripts de línea de comandos para interactuar con la API, útiles para la automatización o las búsquedas rápidas. Foros/Comunidades: Consulta los foros de OpenSubtitles o las comunidades de desarrolladores relacionadas para obtener debates, ejemplos y posibles herramientas de terceros que utilicen la API.
El uso de un wrapper bien mantenido puede acelerar significativamente el desarrollo, pero comprender las llamadas a la API subyacentes (como se describe en esta guía) sigue siendo crucial para la solución de problemas y el uso avanzado.
Suscripción y precios de la API
OpenSubtitles normalmente ofrece diferentes niveles de acceso a su API:
Nivel gratuito: Por lo general, proporciona acceso básico con límites de velocidad y cuotas de descarga más estrictos. Adecuado para aplicaciones de bajo volumen o desarrollo/pruebas. Niveles VIP/de pago: Ofrecen límites de velocidad significativamente más altos, cuotas de descarga más grandes, acceso a funciones premium (como potencialmente la traducción con IA o un soporte más rápido) y están destinados a aplicaciones comerciales o de alto tráfico.
Consulta la documentación o el sitio web oficial de la API de OpenSubtitles para obtener los detalles más recientes sobre los planes de suscripción, los precios y los límites/funciones específicos asociados con cada nivel. Elige el plan que mejor se adapte al uso esperado y a los requisitos de funciones de tu aplicación.
Conclusión
La API de OpenSubtitles es una potente puerta de entrada a una de las colecciones de subtítulos más grandes del mundo. Al comprender su estructura, los métodos de autenticación, los endpoints principales como /subtitles y /download, y al adherirse a las mejores prácticas, los desarrolladores pueden integrar sin problemas la funcionalidad de subtítulos en sus aplicaciones. Desde simples búsquedas en reproductores multimedia hasta funciones complejas que involucran la traducción con IA, la API proporciona los bloques de construcción para experiencias innovadoras y fáciles de usar. Recuerda consultar la documentación oficial de la API de OpenSubtitles para obtener los detalles, los parámetros y las políticas de los endpoints más actualizados a medida que te embarcas en tu viaje de desarrollo. ¡Feliz codificación!
