Les sous-titres sont une partie indispensable de l'expérience médiatique moderne. Ils comblent les barrières linguistiques, améliorent l'accessibilité pour les malentendants et aident les apprenants de langues du monde entier. Au cœur de l'accessibilité des sous-titres se trouve OpenSubtitles, l'un des référentiels en ligne les plus importants et les plus populaires pour les fichiers de sous-titres. Mais OpenSubtitles est bien plus qu'un simple site web ; il propose une puissante API REST qui permet aux développeurs d'intégrer sa vaste base de données de sous-titres directement dans leurs applications.
Que vous construisiez un lecteur multimédia, un système de gestion de contenu, un outil d'apprentissage des langues ou toute autre application susceptible de bénéficier de l'intégration de sous-titres, l'API OpenSubtitles fournit les outils nécessaires. Ce guide complet vous expliquera tout ce que vous devez savoir pour utiliser efficacement l'API OpenSubtitles, de la configuration initiale et de l'authentification à la recherche, au téléchargement, à la traduction de sous-titres et au respect des meilleures pratiques.
Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?
Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
Qu'est-ce que l'API OpenSubtitles ?
L'API OpenSubtitles est un ensemble d'interfaces de programmation qui permettent aux développeurs d'interagir par programmation avec la base de données OpenSubtitles. Au lieu de rechercher et de télécharger manuellement des sous-titres à partir du site web, les applications peuvent utiliser l'API pour effectuer ces actions automatiquement. Cela ouvre un monde de possibilités pour créer des expériences utilisateur fluides et riches en fonctionnalités.
Principales capacités :
Recherche : Trouvez des sous-titres en fonction de divers critères tels que le titre du film/de l'émission, l'ID IMDB, l'ID TMDB, le hachage du fichier, la langue, etc. Téléchargement : Récupérez des fichiers de sous-titres spécifiques identifiés grâce aux résultats de la recherche. Traduction IA : Tirez parti de l'intelligence artificielle pour traduire des sous-titres existants dans différentes langues. Récupération d'informations : Accédez aux métadonnées des sous-titres et des médias.
Premiers pas : vos premières étapes
Avant de pouvoir effectuer des appels à l'API, il y a quelques prérequis et concepts fondamentaux à comprendre.
1. Point de terminaison de l'API :
Toutes les interactions avec l'API REST OpenSubtitles se font via une seule URL de base :
https://api.opensubtitles.com/api/v1
Tous les points de terminaison spécifiques (comme la recherche ou le téléchargement) sont ajoutés à cette URL de base.
2. Inscription et clé API :
L'accès à l'API nécessite une authentification. La méthode principale consiste à utiliser une clé API.
Inscrivez-vous : Vous avez d'abord besoin d'un compte sur OpenSubtitles. Si vous n'en avez pas, inscrivez-vous sur leur site web. Obtenir une clé API : Une fois inscrit, vous devrez générer une clé API. Cela se fait généralement via votre profil utilisateur ou une section développeur dédiée sur le site web d'OpenSubtitles. Gardez votre clé API en sécurité, car elle identifie les requêtes de votre application.
3. Authentification :
L'API prend en charge deux principales méthodes d'authentification :
Clé API : La méthode la plus simple. Incluez votre clé API dans l'en-tête Api-Key de chaque requête. Api-Key: YOUR_API_KEY Jeton JWT : Pour accéder potentiellement à davantage de fonctionnalités spécifiques à l'utilisateur ou à différentes limites de débit (en fonction de la conception de l'API), vous pouvez vous connecter via le point de terminaison /login (couvert plus tard) pour obtenir un jeton Web JSON (JWT). Ce jeton est ensuite inclus dans l'en-tête Authorization en tant que jeton Bearer. Authorization: Bearer YOUR_JWT_TOKEN
Vous devez généralement fournir l'en-tête Api-Key même lorsque vous utilisez un jeton JWT pour l'identification de l'application.
4. En-têtes essentiels :
Outre les en-têtes d'authentification, chaque requête d'API doit inclure :
Content-Type : Pour les requêtes avec un corps (comme les requêtes POST), cela doit généralement être application/json. Content-Type: application/json **User-Agent :** C'est crucial. L'API nécessite une chaîne User-Agent descriptive qui identifie votre application. Les User-Agents vagues ou par défaut (comme python-requests) peuvent être bloqués. Un bon format est YourAppName v1.0. User-Agent: MySubtitleApp v1.2.3
5. Limitation du débit :
Comme la plupart des API publiques, OpenSubtitles applique des limites de débit pour garantir une utilisation équitable et la stabilité du serveur. Le dépassement de ces limites entraînera des réponses d'erreur (souvent 429 Too Many Requests). Portez une attention particulière aux en-têtes de réponse suivants pour gérer votre débit de requêtes :
X-RateLimit-Limit : Le nombre maximal de requêtes autorisées dans la fenêtre actuelle. X-RateLimit-Remaining : Le nombre de requêtes restantes dans la fenêtre actuelle. X-RateLimit-Reset : L'horodatage (souvent l'heure Unix epoch) lorsque la fenêtre de limitation du débit est réinitialisée. Retry-After : Si vous recevez une erreur 429, cet en-tête indique combien de secondes vous devez attendre avant de réessayer.
La mise en œuvre d'une logique dans votre application pour respecter ces en-têtes est essentielle pour un fonctionnement fiable.
Plongée en profondeur dans l'authentification : le point de terminaison /login
Bien que l'utilisation de la seule clé API soit souvent suffisante, le point de terminaison /login permet à votre application de s'authentifier en tant qu'utilisateur OpenSubtitles spécifique, en obtenant un JWT.
Point de terminaison : POST /login
Objectif : Échanger les informations d'identification de l'utilisateur (nom d'utilisateur/mot de passe) contre un jeton d'authentification JWT.
Corps de la requête :
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
En-têtes :
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Réponse réussie (exemple) :
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // C'est le JWT
"status": 200
}
Utilisation du JWT :
Une fois obtenu, incluez cette valeur token dans l'en-tête Authorization pour les requêtes suivantes :
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
L'utilisation de JWT peut donner accès à des quotas de téléchargement spécifiques à l'utilisateur ou à d'autres fonctionnalités liées au niveau de compte ou au statut VIP de l'utilisateur. N'oubliez pas que les JWT ont généralement une durée d'expiration, vous devrez donc peut-être vous réauthentifier périodiquement.
Fonctionnalité principale : Recherche de sous-titres (/subtitles)
C'est peut-être le point de terminaison le plus fréquemment utilisé. Il vous permet d'interroger la vaste base de données OpenSubtitles.
Point de terminaison : GET /subtitles
Objectif : Trouver des sous-titres en fonction de divers critères de recherche.
Authentification : Nécessite l'en-tête Api-Key (et éventuellement Authorization: Bearer <token>).
Principaux paramètres de requête :
La puissance de la recherche réside dans ses paramètres de requête flexibles. Vous pouvez les combiner selon vos besoins :
query=<string> : Rechercher par titre de film ou d'épisode (par exemple, query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string> : Rechercher à l'aide de l'ID IMDb (par exemple, imdb_id=tt0133093). C'est souvent plus précis que query. tmdb_id=<integer> : Rechercher à l'aide de l'ID The Movie Database (TMDb) (par exemple, tmdb_id=603). Également très précis. parent_tmdb_id=<integer> : Pour rechercher des épisodes, utilisez l'ID TMDb de l'émission (par exemple, parent_tmdb_id=1399 pour Game of Thrones). season_number=<integer> : Combinez avec parent_tmdb_id (ou imdb_id de l'émission) pour trouver des sous-titres pour une saison spécifique. episode_number=<integer> : Combinez avec parent_tmdb_id (ou imdb_id de l'émission) et season_number pour un épisode spécifique. languages=<string> : Filtrer par codes de langue (séparés par des virgules, par exemple, languages=en,es, languages=fr). Utilisez les codes ISO 639-2B (comme eng, spa, fre). moviehash=<string> : Rechercher à l'aide d'un hachage unique calculé à partir du fichier vidéo. Cela fournit la correspondance la plus précise si vous avez le fichier vidéo lui-même. Le calcul de ce hachage nécessite généralement des bibliothèques ou des outils spécifiques. type=<string> : Filtrer par type (movie ou episode). hearing_impaired=<include|exclude|only> : Filtrer les sous-titres conçus pour les malentendants. machine_translated=<include|exclude|only> : Filtrer en fonction de la traduction automatique des sous-titres. ai_translated=<include|exclude|only> : Filtrer en fonction de la traduction des sous-titres à l'aide de la fonctionnalité IA de l'API. order_by=<field> : Trier les résultats (par exemple, order_by=download_count). order_direction=<asc|desc> : Spécifier le sens de tri.
Exemple de requête de recherche (recherche de sous-titres en anglais pour "Inception" via l'ID 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
Interprétation des résultats de la recherche :
La réponse est un objet JSON contenant un tableau data. Chaque élément du tableau représente une correspondance de sous-titres.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // ID du sous-titre (utile mais pas pour le téléchargement)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // ID hérité
"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": { // Informations sur le film/l'épisode
"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": [
// ... liens vers le contenu connexe ...
],
"files": [ // CRUCIAL : Ce tableau contient le(s) fichier(s) pour cette entrée de sous-titre
{
"file_id": 998877, // <<< C'est l'ID nécessaire pour le point de terminaison /download
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Potentiellement plus de fichiers s'il s'agit d'un sous-titre en plusieurs parties (par exemple, CD1, CD2)
]
}
},
// ... plus de résultats de sous-titres ...
]
}
L'information la plus importante nécessaire pour le téléchargement est le file_id trouvé dans le tableau attributes.files. Notez qu'une seule entrée de sous-titre (élément du tableau data) peut contenir plusieurs fichiers (par exemple, pour les anciennes versions CD1/CD2). Votre application doit généralement sélectionner le file_id approprié en fonction de critères tels que cd_number ou file_name.
Fonctionnalité principale : Téléchargement de sous-titres (/download)
Une fois que vous avez identifié le fichier de sous-titres souhaité à l'aide du point de terminaison /subtitles et extrait son file_id, vous pouvez utiliser le point de terminaison /download pour obtenir un lien temporaire vers le fichier de sous-titres réel.
Point de terminaison : POST /download
Objectif : Demander un lien de téléchargement pour un fichier de sous-titres spécifique.
Authentification : Nécessite l'en-tête Api-Key et une authentification utilisateur valide (soit un jeton JWT connecté dans l'en-tête Authorization, soit potentiellement des autorisations spécifiques de clé API, en fonction de la politique de l'API – le JWT est souvent préféré/requis pour les téléchargements afin de suivre les quotas).
Corps de la requête :
{
"file_id": 998877 // Le file_id obtenu à partir des résultats de la recherche
// Des paramètres facultatifs tels que "sub_format", "file_name", "in_fps", "out_fps" peuvent être disponibles pour la conversion à la volée
}
En-têtes :
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Probablement requis) User-Agent: YourAppName v1.0
Réponse réussie (exemple) :
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // URL de téléchargement temporaire
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Nombre de requêtes disponibles pour ce lien/fichier spécifique ? (Vérifiez les documents)
"remaining": 95, // Quota de téléchargement restant de l'utilisateur pour la journée/période
"message": "Download count successful.",
"reset_time": "2023-10-27T12:00:00Z", // Quand le quota de téléchargement pourrait être réinitialisé
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Gestion du téléchargement :
Effectuez la requête POST vers /download avec le file_id correct. Vérifiez le code d'état de la réponse pour le succès (par exemple, 200 OK). Extrayez la valeur link de la réponse JSON. Effectuez une requête GET HTTP standard vers cette URL link. Cette requête ne nécessite pas généralement les en-têtes de clé API ou d'autorisation, car le lien lui-même est pré-autorisé. La réponse à la requête GET sur l'URL link sera le contenu réel du fichier de sous-titres (par exemple, le texte du fichier SRT). Enregistrez ce contenu dans un fichier (par exemple, en utilisant le file_name fourni).
Important : Les liens de téléchargement (link) sont généralement temporaires et peuvent expirer après une courte période ou un certain nombre d'utilisations. Ne stockez pas ces liens pour une utilisation à long terme ; récupérez un nouveau lien via le point de terminaison /download chaque fois qu'un téléchargement est nécessaire. Surveillez également le nombre de téléchargements remaining pour éviter d'épuiser le quota de l'utilisateur.
Fonctionnalités avancées : Traduction IA (/ai-translation)
Un ajout plus récent à la boîte à outils OpenSubtitles est la fonctionnalité de traduction basée sur l'IA.
Point de terminaison : POST /ai-translation (ou similaire, vérifiez le point de terminaison exact dans les documents)
Objectif : Traduire un fichier de sous-titres existant dans une autre langue à l'aide de modèles d'IA.
Comment ça marche (conceptuel) :
Vous fournissez probablement le file_id du sous-titre source que vous souhaitez traduire. Vous spécifiez la target_language (par exemple, target_language=de pour l'allemand). L'API traite la requête, mettant potentiellement en file d'attente la tâche de traduction. La réponse peut indiquer l'état de la tâche ou fournir un nouveau file_id ou un lien de téléchargement pour le sous-titre traduit une fois terminé.
Cas d'utilisation :
Rendre les sous-titres disponibles dans des langues qui ne sont pas initialement présentes dans la base de données. Offrir aux utilisateurs des options de traduction à la demande au sein de votre application.
Considérations :
Les traductions IA peuvent avoir des coûts associés ou des limites de débit/quotas spécifiques, potentiellement liés aux niveaux VIP ou d'abonnement. La qualité de la traduction IA peut varier en fonction de la paire de langues et de la complexité du texte source. Cette fonctionnalité peut nécessiter des autorisations utilisateur spécifiques ou des niveaux d'abonnement. Consultez la documentation de l'API pour plus de détails sur l'utilisation, les paramètres et les limitations.
Meilleures pratiques pour l'intégration de l'API
Pour vous assurer que votre application interagit en douceur et de manière responsable avec l'API OpenSubtitles, suivez ces bonnes pratiques :
Mettre en cache les réponses : En particulier pour les résultats de recherche (/subtitles) qui ne changent pas rapidement. Si un utilisateur recherche le même film/épisode plusieurs fois, servez le résultat mis en cache au lieu de contacter l'API à plusieurs reprises. Mettez en œuvre une mise en cache intelligente avec des délais d'expiration raisonnables. Respecter les limites de débit : Surveillez activement les en-têtes X-RateLimit-* et Retry-After. Mettez en œuvre des stratégies de repli exponentiel si vous atteignez la limite (attendez plus longtemps après une limitation de débit répétée). Ne sondez pas l'API de manière agressive. Utiliser des identificateurs spécifiques : Dans la mesure du possible, recherchez à l'aide de imdb_id ou tmdb_id au lieu de query. Ceux-ci fournissent des résultats beaucoup plus précis et réduisent l'ambiguïté. Utilisez moviehash pour la plus grande précision si le fichier vidéo est disponible. Fournir un User-Agent clair : Utilisez une chaîne User-Agent unique et descriptive (par exemple, MyMediaPlayerApp/2.1 (contact@myapp.com)). Cela aide OpenSubtitles à identifier les sources de trafic et à résoudre les problèmes. Les agents génériques peuvent être bloqués. Gérer les erreurs avec élégance : Vérifiez les codes d'état HTTP pour chaque réponse. Mettez en œuvre une logique pour gérer les erreurs courantes telles que 401 Unauthorized (clé API/JWT non valide), 403 Forbidden (autorisation refusée), 404 Not Found, 429 Too Many Requests et les erreurs de serveur 5xx. Fournissez des commentaires informatifs à l'utilisateur. Gérer les quotas de téléchargement : Tenez compte des limites de téléchargement quotidiennes/périodiques associées au compte de l'utilisateur (ou à la clé API). Informez les utilisateurs s'ils approchent ou ont dépassé leur quota. Utilisez le champ remaining dans la réponse /download. Optimiser les recherches : Ne demandez pas de données inutiles. Utilisez des paramètres tels que languages, type, hearing_impaired, etc., pour affiner les résultats côté serveur plutôt que de filtrer de grands ensembles de données côté client. Sécuriser votre clé API : Traitez votre clé API comme un mot de passe. Ne l'intégrez pas directement dans le code côté client. Stockez-la en toute sécurité sur votre serveur.
Wrappers, scripts et ressources communautaires
Bien que ce guide couvre l'interaction directe avec l'API, l'écosystème OpenSubtitles comprend souvent des ressources développées par la communauté.
Wrappers d'API : Recherchez des bibliothèques ou des SDK pour votre langage de programmation (par exemple, Python, JavaScript, Java) sur des plateformes telles que GitHub ou des gestionnaires de packages (PyPI, npm). Ces wrappers peuvent simplifier les appels d'API, gérer l'authentification et analyser les réponses. Scripts : Divers outils ou scripts en ligne de commande peuvent exister pour interagir avec l'API, utiles pour l'automatisation ou les recherches rapides. Forums/Communautés : Consultez les forums OpenSubtitles ou les communautés de développeurs connexes pour les discussions, les exemples et les outils potentiels de tiers utilisant l'API.
L'utilisation d'un wrapper bien maintenu peut accélérer considérablement le développement, mais la compréhension des appels d'API sous-jacents (comme décrit dans ce guide) reste cruciale pour le dépannage et l'utilisation avancée.
Abonnement et tarification de l'API
OpenSubtitles propose généralement différents niveaux d'accès à son API :
Niveau gratuit : Fournit généralement un accès de base avec des limites de débit et des quotas de téléchargement plus stricts. Convient aux applications à faible volume ou au développement/aux tests. Niveaux VIP/payants : Offrent des limites de débit nettement plus élevées, des quotas de téléchargement plus importants, un accès à des fonctionnalités premium (comme potentiellement la traduction IA ou une assistance plus rapide) et sont destinés aux applications commerciales ou à fort trafic.
Consultez la documentation ou le site web officiel de l'API OpenSubtitles pour obtenir les informations les plus récentes sur les plans d'abonnement, les prix et les limites/fonctionnalités spécifiques associées à chaque niveau. Choisissez le plan qui correspond le mieux à l'utilisation prévue de votre application et à ses exigences en matière de fonctionnalités.
Conclusion
L'API OpenSubtitles est une passerelle puissante vers l'une des plus grandes collections de sous-titres au monde. En comprenant sa structure, ses méthodes d'authentification, ses points de terminaison principaux comme /subtitles et /download, et en respectant les meilleures pratiques, les développeurs peuvent intégrer de manière transparente la fonctionnalité de sous-titres dans leurs applications. Des recherches simples dans les lecteurs multimédias aux fonctionnalités complexes impliquant la traduction IA, l'API fournit les éléments constitutifs d'expériences innovantes et conviviales. N'oubliez pas de consulter la documentation officielle de l'API OpenSubtitles pour obtenir les informations les plus récentes sur les points de terminaison, les paramètres et les politiques, au fur et à mesure que vous vous lancez dans votre parcours de développement. Bon codage !
