Untertitel sind ein unverzichtbarer Bestandteil des modernen Medienerlebnisses. Sie überbrücken Sprachbarrieren, verbessern die Barrierefreiheit für Hörgeschädigte und unterstützen Sprachlerner weltweit. Im Zentrum der Barrierefreiheit von Untertiteln steht OpenSubtitles, eine der größten und beliebtesten Online-Repositories für Untertiteldateien. Aber OpenSubtitles ist mehr als nur eine Website; es bietet eine leistungsstarke REST-API, mit der Entwickler seine riesige Untertiteldatenbank direkt in ihre Anwendungen integrieren können.
Egal, ob Sie einen Media Player, ein Content-Management-System, ein Sprachlernwerkzeug oder eine Anwendung entwickeln, die von der Untertitelintegration profitieren könnte, die OpenSubtitles API bietet die notwendigen Werkzeuge. Dieser umfassende Leitfaden führt Sie durch alles, was Sie wissen müssen, um die OpenSubtitles API effektiv zu nutzen, von der Ersteinrichtung und Authentifizierung bis hin zum Suchen, Herunterladen, Übersetzen von Untertiteln und der Einhaltung bewährter Verfahren.
Benötigen Sie eine integrierte All-in-One-Plattform für Ihr Entwicklerteam, um mit maximaler Produktivität zusammenzuarbeiten?
Apidog liefert alle Ihre Anforderungen und ersetzt Postman zu einem viel günstigeren Preis!
Was ist die OpenSubtitles API?
Die OpenSubtitles API ist eine Reihe von Programmierschnittstellen, die es Entwicklern ermöglichen, programmatisch mit der OpenSubtitles-Datenbank zu interagieren. Anstatt manuell nach Untertiteln auf der Website zu suchen und diese herunterzuladen, können Anwendungen die API verwenden, um diese Aktionen automatisch auszuführen. Dies eröffnet eine Welt voller Möglichkeiten zur Erstellung nahtloser und funktionsreicher Benutzererlebnisse.
Hauptfunktionen:
Suchen: Finden Sie Untertitel basierend auf verschiedenen Kriterien wie Film-/Serientitel, IMDB-ID, TMDB-ID, Dateihash, Sprache und mehr. Herunterladen: Rufen Sie bestimmte Untertiteldateien ab, die über Suchergebnisse identifiziert wurden. KI-Übersetzung: Nutzen Sie künstliche Intelligenz, um vorhandene Untertitel in verschiedene Sprachen zu übersetzen. Informationsabruf: Greifen Sie auf Metadaten zu Untertiteln und Medien zu.
Erste Schritte: Ihre ersten Schritte
Bevor Sie Aufrufe an die API tätigen können, gibt es einige Voraussetzungen und grundlegende Konzepte, die Sie verstehen müssen.
1. API-Endpunkt:
Alle Interaktionen mit der OpenSubtitles REST API erfolgen über eine einzige Basis-URL:
https://api.opensubtitles.com/api/v1
Alle spezifischen Endpunkte (wie Suchen oder Herunterladen) werden an diese Basis-URL angehängt.
2. Registrierung und API-Schlüssel:
Der Zugriff auf die API erfordert eine Authentifizierung. Die primäre Methode beinhaltet die Verwendung eines API-Schlüssels.
Registrieren: Sie benötigen zuerst ein Konto auf OpenSubtitles. Wenn Sie keines haben, registrieren Sie sich auf deren Website. API-Schlüssel abrufen: Nach der Registrierung müssen Sie einen API-Schlüssel generieren. Dies geschieht in der Regel über Ihr Benutzerprofil oder einen dedizierten Entwicklerbereich auf der OpenSubtitles-Website. Bewahren Sie Ihren API-Schlüssel sicher auf, da er die Anfragen Ihrer Anwendung identifiziert.
3. Authentifizierung:
Die API unterstützt zwei Hauptauthentifizierungsmethoden:
API-Schlüssel: Die einfachste Methode. Fügen Sie Ihren API-Schlüssel in den Api-Key-Header jeder Anfrage ein. Api-Key: YOUR_API_KEY JWT-Token: Für den potenziellen Zugriff auf weitere benutzerspezifische Funktionen oder unterschiedliche Ratenbegrenzungen (je nach API-Design) können Sie sich über den /login-Endpunkt (später behandelt) anmelden, um ein JSON Web Token (JWT) zu erhalten. Dieses Token wird dann im Authorization-Header als Bearer-Token enthalten. Authorization: Bearer YOUR_JWT_TOKEN
Sie müssen in der Regel weiterhin den Api-Key-Header angeben, auch wenn Sie ein JWT-Token zur Anwendungsidentifizierung verwenden.
4. Wesentliche Header:
Neben Authentifizierungs-Headern muss jede API-Anfrage Folgendes enthalten:
Content-Type: Für Anfragen mit einem Body (wie POST-Anfragen) sollte dies in der Regel application/json sein. Content-Type: application/json **User-Agent:** Dies ist entscheidend. Die API benötigt eine beschreibende User-Agent-Zeichenfolge, die Ihre Anwendung identifiziert. Vage oder standardmäßige User-Agents (wie python-requests) könnten blockiert werden. Ein gutes Format ist YourAppName v1.0. User-Agent: MySubtitleApp v1.2.3
5. Ratenbegrenzung:
Wie die meisten öffentlichen APIs erzwingt OpenSubtitles Ratenbegrenzungen, um eine faire Nutzung und Serverstabilität zu gewährleisten. Das Überschreiten dieser Limits führt zu Fehlerantworten (oft 429 Too Many Requests). Achten Sie genau auf die folgenden Antwort-Header, um Ihre Anforderungsrate zu verwalten:
X-RateLimit-Limit: Die maximale Anzahl von Anfragen, die im aktuellen Fenster zulässig sind. X-RateLimit-Remaining: Die Anzahl der verbleibenden Anfragen im aktuellen Fenster. X-RateLimit-Reset: Der Zeitstempel (oft Unix-Epochenzeit), zu dem sich das Ratenbegrenzungsfenster zurücksetzt. Retry-After: Wenn Sie einen 429-Fehler erhalten, gibt dieser Header an, wie viele Sekunden Sie warten sollten, bevor Sie es erneut versuchen.
Die Implementierung von Logik in Ihrer Anwendung, um diese Header zu berücksichtigen, ist für einen zuverlässigen Betrieb unerlässlich.
Authentifizierung im Detail: Der /login-Endpunkt
Während die Verwendung nur des API-Schlüssels oft ausreicht, ermöglicht der /login-Endpunkt Ihrer Anwendung, sich als bestimmter OpenSubtitles-Benutzer zu authentifizieren und ein JWT zu erhalten.
Endpunkt: POST /login
Zweck: Um Benutzeranmeldeinformationen (Benutzername/Passwort) gegen ein JWT-Authentifizierungstoken auszutauschen.
Anfrage-Body:
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
Header:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Erfolgreiche Antwort (Beispiel):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Dies ist das JWT
"status": 200
}
Verwendung des JWT:
Fügen Sie diesen token-Wert nach dem Erhalt in den Authorization-Header für nachfolgende Anfragen ein:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Die Verwendung von JWT könnte den Zugriff auf benutzerspezifische Download-Kontingente oder andere Funktionen gewähren, die an die Kontostufe oder den VIP-Status des Benutzers gebunden sind. Denken Sie daran, dass JWTs in der Regel eine Ablaufzeit haben, sodass Sie sich möglicherweise regelmäßig erneut authentifizieren müssen.
Kernfunktionalität: Suchen nach Untertiteln (/subtitles)
Dies ist vielleicht der am häufigsten verwendete Endpunkt. Er ermöglicht es Ihnen, die riesige OpenSubtitles-Datenbank abzufragen.
Endpunkt: GET /subtitles
Zweck: Um Untertitel basierend auf verschiedenen Suchkriterien zu finden.
Authentifizierung: Erfordert den Api-Key-Header (und optional Authorization: Bearer <token>).
Wichtige Abfrageparameter:
Die Leistungsfähigkeit der Suche liegt in ihren flexiblen Abfrageparametern. Sie können diese nach Bedarf kombinieren:
query=<string>: Suchen nach Film- oder Episodentitel (z. B. query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Suchen mit der IMDb-ID (z. B. imdb_id=tt0133093). Dies ist oft genauer als query. tmdb_id=<integer>: Suchen mit der TMDb-ID (The Movie Database) (z. B. tmdb_id=603). Auch sehr genau. parent_tmdb_id=<integer>: Verwenden Sie für die Suche nach Episoden die TMDb-ID der Serie (z. B. parent_tmdb_id=1399 für Game of Thrones). season_number=<integer>: Kombinieren Sie mit parent_tmdb_id (oder imdb_id der Serie), um Untertitel für eine bestimmte Staffel zu finden. episode_number=<integer>: Kombinieren Sie mit parent_tmdb_id (oder imdb_id der Serie) und season_number für eine bestimmte Episode. languages=<string>: Filtern nach Sprachcodes (durch Kommas getrennt, z. B. languages=en,es, languages=fr). Verwenden Sie ISO 639-2B-Codes (wie eng, spa, fre). moviehash=<string>: Suchen mit einem eindeutigen Hash, der aus der Videodatei berechnet wurde. Dies liefert die genaueste Übereinstimmung, wenn Sie die Videodatei selbst haben. Die Berechnung dieses Hashs erfordert in der Regel bestimmte Bibliotheken oder Tools. type=<string>: Filtern nach Typ (movie oder episode). hearing_impaired=<include|exclude|only>: Filtern Sie nach Untertiteln, die für Hörgeschädigte konzipiert sind. machine_translated=<include|exclude|only>: Filtern Sie danach, ob Untertitel maschinell übersetzt wurden. ai_translated=<include|exclude|only>: Filtern Sie danach, ob Untertitel mithilfe der KI-Funktion der API übersetzt wurden. order_by=<field>: Ergebnisse sortieren (z. B. order_by=download_count). order_direction=<asc|desc>: Sortierrichtung angeben.
Beispiel-Suchanfrage (Englische Untertitel für "Inception" über die TMDb-ID finden):
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
Interpretieren der Suchergebnisse:
Die Antwort ist ein JSON-Objekt, das ein data-Array enthält. Jedes Element im Array stellt eine Untertitelübereinstimmung dar.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"data": [
{
"id": "1234567", // Untertitel-ID (nützlich, aber nicht für den Download)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // Legacy-ID
"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": { // Informationen über den Film/die Episode
"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": [
// ... Links zu verwandten Inhalten ...
],
"files": [ // ENTSCHEIDEND: Dieses Array enthält die Datei(en) für diesen Untertiteleintrag
{
"file_id": 998877, // <<< DIES ist die ID, die für den /download-Endpunkt benötigt wird
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Möglicherweise weitere Dateien, wenn es sich um einen mehrteiligen Untertitel handelt (z. B. CD1, CD2)
]
}
},
// ... weitere Untertitel-Ergebnisse ...
]
}
Die wichtigste Information, die zum Herunterladen benötigt wird, ist die file_id, die im attributes.files-Array gefunden wird. Beachten Sie, dass ein einzelner Untertiteleintrag (data-Array-Element) mehrere Dateien enthalten kann (z. B. für ältere CD1/CD2-Releases). Ihre Anwendung sollte in der Regel die entsprechende file_id basierend auf Kriterien wie cd_number oder file_name auswählen.
Kernfunktionalität: Herunterladen von Untertiteln (/download)
Sobald Sie die gewünschte Untertiteldatei mithilfe des /subtitles-Endpunkts identifiziert und deren file_id extrahiert haben, können Sie den /download-Endpunkt verwenden, um einen temporären Link zur eigentlichen Untertiteldatei zu erhalten.
Endpunkt: POST /download
Zweck: Um einen Download-Link für eine bestimmte Untertiteldatei anzufordern.
Authentifizierung: Erfordert den Api-Key-Header und eine gültige Benutzerauthentifizierung (entweder ein angemeldetes JWT-Token im Authorization-Header oder möglicherweise bestimmte API-Schlüsselberechtigungen, abhängig von der API-Richtlinie – oft wird JWT für Downloads bevorzugt/erforderlich, um Kontingente zu verfolgen).
Anfrage-Body:
{
"file_id": 998877 // Die file_id, die aus den Suchergebnissen erhalten wurde
// Optionale Parameter wie "sub_format", "file_name", "in_fps", "out_fps" sind möglicherweise für die Konvertierung im laufenden Betrieb verfügbar
}
Header:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Wahrscheinlich erforderlich) User-Agent: YourAppName v1.0
Erfolgreiche Antwort (Beispiel):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // Temporäre Download-URL
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Anzahl der verfügbaren Anfragen für diesen bestimmten Link/diese Datei? (Dokumente prüfen)
"remaining": 95, // Verbleibendes Download-Kontingent des Benutzers für den Tag/Zeitraum
"message": "Download count successful.",
"reset_time": "2023-10-27T12:00:00Z", // Wann sich das Download-Kontingent zurücksetzen könnte
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Behandlung des Downloads:
Stellen Sie die POST-Anfrage an /download mit der richtigen file_id. Überprüfen Sie den Antwortstatuscode auf Erfolg (z. B. 200 OK). Extrahieren Sie den link-Wert aus der JSON-Antwort. Stellen Sie eine Standard-HTTP-GET-Anfrage an diese link-URL. Diese Anfrage erfordert in der Regel nicht die API-Schlüssel- oder Autorisierungs-Header, da der Link selbst vorautorisiert ist. Die Antwort auf die GET-Anfrage an die link-URL ist der eigentliche Untertiteldateiinhalte (z. B. der Text der SRT-Datei). Speichern Sie diesen Inhalt in einer Datei (z. B. mithilfe des bereitgestellten file_name).
Wichtig: Die Download-Links (link) sind in der Regel temporär und können nach kurzer Zeit oder einer bestimmten Anzahl von Verwendungen ablaufen. Speichern Sie diese Links nicht für die langfristige Nutzung; rufen Sie jedes Mal, wenn ein Download benötigt wird, einen neuen Link über den /download-Endpunkt ab. Überwachen Sie außerdem die remaining-Downloadanzahl, um zu vermeiden, dass das Kontingent des Benutzers erschöpft wird.
Erweiterte Funktionen: KI-Übersetzung (/ai-translation)
Eine neuere Ergänzung des OpenSubtitles-Toolkits ist die KI-gestützte Übersetzungsfunktion.
Endpunkt: POST /ai-translation (oder ähnlich, genauen Endpunkt in den Dokumenten prüfen)
Zweck: Um eine vorhandene Untertiteldatei mithilfe von KI-Modellen in eine andere Sprache zu übersetzen.
So funktioniert es (konzeptionell):
Sie geben wahrscheinlich die file_id des Quelluntertitels an, den Sie übersetzen möchten. Sie geben die target_language an (z. B. target_language=de für Deutsch). Die API verarbeitet die Anfrage und stellt möglicherweise den Übersetzungsauftrag in die Warteschlange. Die Antwort kann den Auftragsstatus angeben oder eine neue file_id oder einen Download-Link für den übersetzten Untertitel bereitstellen, sobald er fertiggestellt wurde.
Anwendungsfälle:
Bereitstellen von Untertiteln in Sprachen, die ursprünglich nicht in der Datenbank vorhanden waren. Bereitstellen von On-Demand-Übersetzungsoptionen für Benutzer innerhalb Ihrer Anwendung.
Überlegungen:
KI-Übersetzungen können mit Kosten oder bestimmten Ratenbegrenzungen/Kontingenten verbunden sein, die möglicherweise an VIP- oder Abonnementstufen gebunden sind. Die Qualität der KI-Übersetzung kann je nach Sprachpaar und Komplexität des Quelltexts variieren. Diese Funktion erfordert möglicherweise bestimmte Benutzerberechtigungen oder Abonnementstufen. Konsultieren Sie die API-Dokumentation für Details zu Nutzung, Parametern und Einschränkungen.
Best Practices für die API-Integration
Um sicherzustellen, dass Ihre Anwendung reibungslos und verantwortungsvoll mit der OpenSubtitles API interagiert, befolgen Sie diese Best Practices:
Antworten zwischenspeichern: Insbesondere für Suchergebnisse (/subtitles), die sich nicht schnell ändern. Wenn ein Benutzer mehrmals nach demselben Film/derselben Episode sucht, stellen Sie das zwischengespeicherte Ergebnis bereit, anstatt die API wiederholt aufzurufen. Implementieren Sie intelligentes Caching mit angemessenen Ablaufzeiten. Ratenbegrenzungen einhalten: Überwachen Sie aktiv die X-RateLimit-*- und Retry-After-Header. Implementieren Sie exponentielle Backoff-Strategien, wenn Sie das Limit erreichen (längere Wartezeit nach wiederholter Ratenbegrenzung). Fragen Sie die API nicht aggressiv ab. Verwenden Sie bestimmte Kennungen: Suchen Sie nach Möglichkeit mit imdb_id oder tmdb_id anstelle von query. Diese liefern viel genauere Ergebnisse und reduzieren Mehrdeutigkeiten. Verwenden Sie moviehash für die höchste Genauigkeit, wenn die Videodatei verfügbar ist. Stellen Sie einen eindeutigen User-Agent bereit: Verwenden Sie eine eindeutige und beschreibende User-Agent-Zeichenfolge (z. B. MyMediaPlayerApp/2.1 (contact@myapp.com)). Dies hilft OpenSubtitles, Datenverkehrsquellen zu identifizieren und Probleme zu beheben. Generische Agents können blockiert werden. Fehler ordnungsgemäß behandeln: Überprüfen Sie die HTTP-Statuscodes für jede Antwort. Implementieren Sie Logik zur Behandlung häufiger Fehler wie 401 Unauthorized (ungültiger API-Schlüssel/JWT), 403 Forbidden (Berechtigung verweigert), 404 Not Found, 429 Too Many Requests und 5xx-Serverfehler. Geben Sie dem Benutzer informatives Feedback. Download-Kontingente verwalten: Beachten Sie die täglichen/periodischen Download-Limits, die mit dem Konto (oder API-Schlüssel) des Benutzers verknüpft sind. Informieren Sie Benutzer, wenn sie sich ihrem Kontingent nähern oder es überschritten haben. Verwenden Sie das Feld remaining in der /download-Antwort. Suchen optimieren: Fordern Sie keine unnötigen Daten an. Verwenden Sie Parameter wie languages, type, hearing_impaired usw., um die Ergebnisse serverseitig einzugrenzen, anstatt große Datensätze clientseitig zu filtern. Sichern Sie Ihren API-Schlüssel: Behandeln Sie Ihren API-Schlüssel wie ein Passwort. Betten Sie es nicht direkt in den Client-seitigen Code ein. Speichern Sie es sicher auf Ihrem Server.
Wrapper, Skripte und Community-Ressourcen
Während dieser Leitfaden die direkte API-Interaktion behandelt, umfasst das OpenSubtitles-Ökosystem häufig von der Community entwickelte Ressourcen.
API-Wrapper: Suchen Sie nach Bibliotheken oder SDKs für Ihre Programmiersprache (z. B. Python, JavaScript, Java) auf Plattformen wie GitHub oder Paketmanagern (PyPI, npm). Diese Wrapper können API-Aufrufe vereinfachen, die Authentifizierung verarbeiten und Antworten analysieren. Skripte: Es können verschiedene Befehlszeilentools oder Skripte für die Interaktion mit der API vorhanden sein, die für die Automatisierung oder schnelle Nachschläge nützlich sind. Foren/Communities: Überprüfen Sie OpenSubtitles-Foren oder verwandte Entwickler-Communities auf Diskussionen, Beispiele und potenzielle Tools von Drittanbietern, die die API verwenden.
Die Verwendung eines gut gewarteten Wrappers kann die Entwicklung erheblich beschleunigen, aber das Verständnis der zugrunde liegenden API-Aufrufe (wie in diesem Leitfaden beschrieben) bleibt für die Fehlerbehebung und erweiterte Nutzung von entscheidender Bedeutung.
API-Abonnement und Preise
OpenSubtitles bietet in der Regel verschiedene Zugriffsebenen auf seine API:
Kostenlose Stufe: Bietet in der Regel grundlegenden Zugriff mit strengeren Ratenbegrenzungen und Download-Kontingenten. Geeignet für Anwendungen mit geringem Volumen oder Entwicklung/Tests. VIP-/Bezahlte Stufen: Bieten deutlich höhere Ratenbegrenzungen, größere Download-Kontingente, Zugriff auf Premium-Funktionen (wie möglicherweise KI-Übersetzung oder schnelleren Support) und sind für kommerzielle Anwendungen oder Anwendungen mit hohem Datenverkehr vorgesehen.
Lesen Sie die offizielle OpenSubtitles API-Dokumentation oder die Website für die aktuellsten Details zu Abonnementplänen, Preisen und den spezifischen Limits/Funktionen, die mit jeder Stufe verbunden sind. Wählen Sie den Plan, der am besten zur erwarteten Nutzung und den Funktionsanforderungen Ihrer Anwendung passt.
Fazit
Die OpenSubtitles API ist ein leistungsstarkes Tor zu einer der weltweit größten Untertitelsammlungen. Durch das Verständnis ihrer Struktur, Authentifizierungsmethoden, Kernendpunkte wie /subtitles und /download und die Einhaltung bewährter Verfahren können Entwickler die Untertitelfunktionalität nahtlos in ihre Anwendungen integrieren. Von einfachen Nachschlägen in Media Playern bis hin zu komplexen Funktionen, die KI-Übersetzung beinhalten, bietet die API die Bausteine für innovative und benutzerfreundliche Erlebnisse. Denken Sie daran, die offizielle OpenSubtitles API-Dokumentation zu konsultieren, um die aktuellsten Endpunktdetails, Parameter und Richtlinien zu erhalten, während Sie sich auf Ihre Entwicklungsreise begeben. Viel Spaß beim Codieren!
