So erhalten Sie einen TMDB API Schlüssel und fragen die TMDB API ab

Die Movie Database (TMDB) ist ein von der Community aufgebauter Katalog für Filme, Fernsehsendungen, Besetzungen und Artworks. Ihre API ist für die nicht-kommerzielle Nutzung kostenlos, solange Sie TMDB als Quelle angeben, was sie zum üblichen Ausgangspunkt auf jeder Liste von kostenlosen Film-APIs macht. Der Haken ist das Onboarding: TMDB gibt Ihnen zwei verschiedene Zugangsdaten, und der offizielle Leitfaden für den Einstieg geht davon aus, dass Sie bereits wissen, welche davon zu verwenden sind.

Dieser Leitfaden deckt den gesamten Weg ab: Konto, Schlüsselanfrage, v3-Schlüssel versus v4-Lesezugriffstoken, erste Such- und Detailaufrufe in curl und Python, dieselben Aufrufe als Test in Apidog gespeichert, sowie die Ratenbegrenzungen, Zuschreibungsregeln und Fehler, die Ihnen am ersten Tag begegnen werden.

Was Sie vor dem Start benötigen

• Ein TMDB-Konto mit einer verifizierten E-Mail-Adresse. Die API lehnt nicht verifizierte Konten mit einem 401 ab.
• Einen Desktop-Browser. Die TMDB-Dokumentation besagt, dass die API-Registrierungsseiten nicht für mobile Geräte optimiert sind.
• curl, oder Python 3 mit dem requests-Paket.
• Apidog, um den Token sicher zu speichern und die Anfragen zu verwalten. Laden Sie Apidog herunter für macOS, Windows oder Linux.

Schritt 1: Ein TMDB-Konto erstellen

Gehen Sie zu themoviedb.org, klicken Sie auf „TMDB beitreten“ (Join TMDB) und registrieren Sie sich mit einer E-Mail-Adresse. Öffnen Sie die Verifizierungs-E-Mail und bestätigen Sie diese, bevor Sie die API-Einstellungen berühren. Überspringen Sie diesen Schritt, und Sie werden später auf einen verwirrenden 401-Fehler stoßen, Statuscode 32: „E-Mail nicht verifiziert: Ihre E-Mail-Adresse wurde nicht verifiziert.“

Schritt 2: Den API-Schlüssel anfordern

Sobald Sie angemeldet sind, öffnen Sie Ihre Kontoeinstellungen und klicken Sie in der linken Seitenleiste auf „API“. Die FAQ von TMDB beschreiben dies als den einzigen Weg: „Sie können einen API-Schlüssel beantragen, indem Sie auf den Link ‚API‘ in der linken Seitenleiste Ihrer Kontoeinstellungsseite klicken.“

Sie akzeptieren die API-Nutzungsbedingungen und füllen dann einen kurzen Antrag aus: Was Sie entwickeln, eine URL, falls vorhanden, eine Zusammenfassung, wie Sie die Daten nutzen werden, und die Art der Nutzung. Wählen Sie die Entwickleroption für persönliche Projekte, Prototypen und interne Tools. TMDB stuft ein Projekt als kommerziell ein, „wenn der Hauptzweck darin besteht, Einnahmen zum Vorteil des Eigentümers zu erzielen“, und dieser Weg erfordert eine schriftliche Vereinbarung mit dem Verkaufsteam.

Nach dem Absenden zeigt dieselbe Einstellungsseite zwei Zugangsdaten:

• API-Schlüssel, für v3-Authentifizierung. Eine 32-stellige Hexadezimalzeichenkette.
• API-Lesezugriffstoken, eine viel längere Zeichenkette im JWT-Stil.

TMDB veröffentlicht keine Überprüfungszeitpläne; in der Praxis erscheinen beide Werte, sobald das Formular durchgegangen ist. Behandeln Sie sie wie jedes andere Geheimnis und halten Sie sie von Commits, Chat-Fenstern und Screenshots fern.

v3 API-Schlüssel vs. v4 Lesezugriffstoken

Die beiden Zugangsdaten sind nicht „alt“ und „neu“. Es sind zwei Wege, dieselbe Anwendung zu identifizieren, und die offizielle Authentifizierungsdokumentation besagt, dass beide „das gleiche Zugriffslevel bieten“.

TMDBs eigene Empfehlung ist der Bearer-Token: „Die Standardmethode zur Authentifizierung ist mit Ihrem Zugriffstoken“, und er „hat den zusätzlichen Vorteil, ein einziger Authentifizierungsprozess zu sein, den Sie sowohl für die v3- als auch für die v4-Methoden verwenden können.“

Verwenden Sie den Bearer-Header, es sei denn, Ihr Client kann keine Header setzen. Das Heraushalten der Zugangsdaten aus der URL ist das gleiche Argument, das hinter jeder Entscheidung bezüglich API-Schlüssel versus Bearer-Token steckt: URLs werden protokolliert, zwischengespeichert und geteilt.

Noch ein Unterschied. Alles in diesem Artikel sind schreibgeschützte Katalogdaten, die nur die Anmeldedaten der Anwendung benötigen. Die v4-API fügt Kontofunktionen wie Listen, Favoriten, Bewertungen und Merklisten hinzu. Das Schreiben dieser Daten für einen TMDB-Benutzer erfordert einen zusätzlichen Handshake: einen Anforderungstoken von /4/auth/request_token, die Benutzergenehmigung und dann einen Benutzerzugriffstoken von /4/auth/access_token. Nichts davon wird benötigt, um Filme zu suchen oder Details zu lesen.

Schritt 3: Ihre erste Anfrage stellen

Alle v3-Aufrufe gehen an https://api.themoviedb.org/3. Zwei Endpunkte decken die meisten ersten Projekte ab: Suche nach Titel, dann Abrufen von Details nach ID.

Film mit curl suchen

curl --request GET \
  --url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
  --header 'Authorization: Bearer YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

Die Antwort ist ein Seitenobjekt mit page, results, total_pages und total_results. Jedes Ergebnis enthält id, title, release_date, overview, poster_path, genre_ids und vote_average. Im Suchbeispiel von TMDB ist der erste Treffer für „Fight Club“ die ID 550, veröffentlicht am 15.10.1999.

Der gleiche Aufruf mit dem v3-Schlüssel sieht so aus. Beachten Sie, dass überhaupt kein Auth-Header vorhanden ist:

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

Filmdetails mit Python abrufen

import os
import requests

TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}


def search_movie(title):
    r = requests.get(
        f"{BASE}/search/movie",
        params={"query": title, "include_adult": "false", "language": "en-US"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]


def movie_details(movie_id):
    r = requests.get(
        f"{BASE}/movie/{movie_id}",
        params={"append_to_response": "credits"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])

Die letzte Zeile ist der Teil, den die Leute oft übersehen. poster_path ist nur ein Pfad. Wie der Leitfaden zu den Bildgrundlagen erklärt, ist eine funktionierende URL https://image.tmdb.org/t/p/, gefolgt von einer Größe wie w500 oder original, und dann dem Pfad. /3/configuration listet jede gültige Größe auf.

Schritt 4: Anfragen in Apidog ausführen und speichern

Sobald die Rohaufrufe funktionieren, verschieben Sie sie an einen Ort, an dem Sie sie nicht verlieren werden. In Apidog dauert dies nur wenige Minuten und Sie erhalten einen gespeicherten, teilbaren Test.

1. Erstellen Sie ein Projekt und fügen Sie eine Umgebung namens „TMDB“ mit zwei Variablen hinzu: base_url auf https://api.themoviedb.org/3 gesetzt und tmdb_token, das Ihr Lesezugriffstoken enthält. Markieren Sie den Token als geheim, damit er in der Benutzeroberfläche maskiert und aus Exporten ferngehalten wird; der Leitfaden zu Umgebungs- und Geheimnisvariablen deckt die Optionen ab.
2. Fügen Sie eine GET-Anfrage zu {{base_url}}/search/movie mit einem query-Parameter hinzu. Wählen Sie auf dem Auth-Tab Bearer Token und geben Sie {{tmdb_token}} ein. Senden Sie es ab und bestätigen Sie, dass Sie einen 200-Status und ein results-Array erhalten.
3. Fügen Sie eine zweite GET-Anfrage zu {{base_url}}/movie/{{movie_id}} hinzu. Extrahieren Sie im Post-Prozessor der ersten Anfrage results[0].id in movie_id, sodass der zweite Aufruf immer dem ersten folgt.
4. Speichern Sie beides als Testszenario mit Zusicherungen: Status gleich 200, total_results größer als 0 und title in der Detailantwort ist nicht leer. Führen Sie es aus, wann immer sich die Integration ändert.

Entwickeln Sie ein Frontend auf Basis dieser Daten? Schalten Sie den Mock-Server für den Such-Endpunkt ein. Apidog generiert eine schema-konforme Antwort, sodass das UI-Team das Poster-Raster ohne einen Live-Token oder echte Anfragen gegen die TMDB-Limits erstellen kann.

Ratenbegrenzungen und Zuschreibungsregeln

Alles Folgende ist aus der TMDB-Dokumentation zitiert.

Ratenbegrenzungen. Die Seite zu den Ratenbegrenzungen von TMDB besagt, dass das ursprüngliche Limit von 40 Anfragen alle 10 Sekunden am 16. Dezember 2019 deaktiviert wurde. Obergrenzen bleiben bestehen, „um unnötig hohe Massenabfragen zu verhindern“, und liegen „irgendwo im Bereich von 40 Anfragen pro Sekunde“. Diese Zahl kann sich ohne vorherige Ankündigung ändern, also respektieren Sie jeden HTTP 429-Fehler, warten Sie und versuchen Sie es erneut.

Kosten. Aus den FAQ: „Unsere API ist für nicht-kommerzielle Zwecke kostenlos nutzbar, solange Sie TMDB als Quelle der Daten und/oder Bilder angeben.“ Kommerzielle Projekte müssen sich an sales@themoviedb.org wenden.

Zuschreibung. Zeigen Sie das TMDB-Logo und diesen Hinweis in Ihrer Anwendung an: „Dieses Produkt verwendet die TMDB-API, wird aber nicht von TMDB unterstützt oder zertifiziert.“ Die API-Nutzungsbedingungen verwenden eine etwas längere Formulierung und erfordern, dass das Logo weniger prominent als Ihr eigenes Branding ist und niemals umgefärbt, gestreckt, gespiegelt oder gedreht wird.

Caching. Die Bedingungen verbieten das Caching von TMDB-Daten für länger als sechs Monate. Speichern Sie, was Sie benötigen, aber planen Sie eine Aktualisierung ein.

Keine SLA. TMDB sagt dies ausdrücklich. Bauen Sie Timeouts und Wiederholungsversuche ein.

Schlüssel-Hygiene. Beide Zugangsdaten gehören in Umgebungsvariablen oder einen Secrets Manager, niemals in den Quellcode. Wenn einer in einem Repository landet, wechseln Sie ihn auf der Einstellungsseite und führen Sie einen API-Schlüssel-Leak-Check über Ihren Verlauf durch.

Häufige Fehler und ihre Bedeutung

TMDB gibt einen JSON-Körper mit status_code und status_message zusammen mit dem HTTP-Status zurück. Die Fehlerreferenz listet Dutzende von Codes auf; dies sind diejenigen, die Ihnen zuerst begegnen werden.

Häufig gestellte Fragen (FAQ)

Ist der TMDB API-Schlüssel kostenlos?

Ja, für nicht-kommerzielle Nutzung mit Quellenangabe. Es gibt keine kostenpflichtige Self-Service-Stufe. Wenn Ihr Projekt Einnahmen generiert, bittet TMDB Sie, eine kommerzielle Vereinbarung über sein Verkaufsteam zu treffen.

Sollte ich den API-Schlüssel oder den Lesezugriffstoken verwenden?

Verwenden Sie den Lesezugriffstoken als Bearer-Header. TMDB bezeichnet ihn als Standard, er funktioniert sowohl mit v3 als auch mit v4 und bleibt aus Ihren URLs heraus. Der v3-Schlüssel existiert für Tools, die nur Abfrageparameter senden können. Wenn das Konzept neu ist, erklärt dieser Grundkurs zum Thema was ein API-Schlüssel ist, das Modell, dem TMDB folgt.

Kann ich TMDB direkt von einem Browser oder einer mobilen App aufrufen?

Das können Sie, aber alles, was an den Client geliefert wird, ist öffentlich, einschließlich Ihres Tokens. Für ein persönliches Projekt ist das ein akzeptiertes Risiko. Für alles, was Benutzer hat, stellen Sie ein kleines Backend oder eine Serverless-Funktion vor TMDB, bewahren Sie den Token dort auf und cachen Sie populäre Anfragen.

Was ist der Unterschied zwischen v3 und v4?

v3 ist der Katalog: Suche, Film- und TV-Details, Personen, Bilder, Entdeckung. v4 deckt Kontofunktionen wie Listen, Favoriten, Bewertungen und Merklisten ab, und seine Schreib-Endpunkte erfordern einen Benutzerzugriffstoken. Ihr Lesezugriffstoken authentifiziert sich gegenüber beiden.

Wohin von hier aus

Sie haben nun einen funktionierenden TMDB API-Schlüssel, eine Regel, welche Zugangsdaten zu senden sind, einen Such-dann-Details-Workflow in curl und Python, und denselben Workflow als Apidog-Testszenario gespeichert. Als Nächstes fügen Sie discover/movie für gefiltertes Browsen hinzu und fügen den Urheberrechtshinweis in Ihre App ein, bevor Sie sie teilen. Alles andere im Katalog verwendet die gleiche Basis-URL, den gleichen Bearer-Header und die gleichen Fehlerstrukturen.