Comment obtenir une clé API TMDB et interroger l'API The Movie Database

The Movie Database (TMDB) est un catalogue de films, d'émissions de télévision, de casting et d'œuvres d'art construit par la communauté. Son API est gratuite pour une utilisation non commerciale tant que vous créditez TMDB, ce qui en fait le point de départ habituel de toute liste d'API de films gratuites. Le hic, c'est l'intégration : TMDB vous fournit deux identifiants différents, et le guide de démarrage officiel suppose que vous savez déjà lequel utiliser.

Ce guide couvre l'intégralité du parcours : compte, demande de clé, clé v3 versus jeton d'accès en lecture v4, premiers appels de recherche et de détails en curl et Python, les mêmes appels enregistrés comme test dans Apidog, ainsi que les limites de débit, les règles d'attribution et les erreurs que vous rencontrerez dès le premier jour.

télécharger l'application

Ce dont vous avez besoin avant de commencer

• Un compte TMDB avec une adresse e-mail vérifiée. L'API refuse les comptes non vérifiés avec un statut 401.
• Un navigateur de bureau. La documentation de TMDB indique que les pages d'enregistrement de l'API ne sont pas optimisées pour les appareils mobiles.
• curl, ou Python 3 avec le package requests.
• Apidog, pour stocker le jeton en toute sécurité et conserver les requêtes. Téléchargez Apidog pour macOS, Windows ou Linux.

Étape 1 : créer un compte TMDB

Rendez-vous sur themoviedb.org, cliquez sur « Rejoindre TMDB » et inscrivez-vous avec une adresse e-mail. Ouvrez l'e-mail de vérification et confirmez-le avant de toucher aux paramètres de l'API. Si vous l'ignorez, vous rencontrerez plus tard un 401 déroutant, code d'état 32 : « E-mail non vérifié : Votre adresse e-mail n'a pas été vérifiée. »

Étape 2 : demander la clé API

Une fois connecté, ouvrez les paramètres de votre compte et cliquez sur « API » dans la barre latérale gauche. La FAQ de TMDB décrit cela comme la seule voie : « Vous pouvez demander une clé API en cliquant sur le lien ‘API’ dans la barre latérale gauche de la page des paramètres de votre compte. »

Vous accepterez les conditions d'utilisation de l'API, puis remplirez une courte candidature : ce que vous construisez, une URL si vous en avez une, un résumé de la manière dont vous utiliserez les données et le type d'utilisation. Choisissez l'option développeur pour les projets personnels, les prototypes et les outils internes. TMDB considère un projet comme commercial « si l'objectif principal est de générer des revenus au profit du propriétaire », et cette voie nécessite un accord écrit avec son équipe de vente.

Après avoir soumis, la même page de paramètres affiche deux identifiants :

• Clé API, étiquetée pour l'authentification v3. Une chaîne hexadécimale de 32 caractères.
• Jeton d'accès en lecture API, une chaîne beaucoup plus longue de style JWT.

TMDB ne publie pas de calendrier de révision ; en pratique, les deux valeurs apparaissent dès que le formulaire est traité. Traitez-les comme n'importe quel autre secret et gardez-les hors des commits, des fenêtres de discussion et des captures d'écran.

Clé API v3 vs jeton d'accès en lecture v4

Les deux identifiants ne sont pas « anciens » et « nouveaux ». Ce sont deux façons d'identifier la même application, et la documentation officielle d'authentification indique que les deux « fournissent le même niveau d'accès. »

La propre recommandation de TMDB est le jeton Bearer : « La méthode par défaut pour s'authentifier est avec votre jeton d'accès », et il « a l'avantage supplémentaire d'être un processus d'authentification unique que vous pouvez utiliser à la fois pour les méthodes v3 et v4. »

Utilisez l'en-tête Bearer à moins que votre client ne puisse pas définir d'en-têtes. Maintenir l'identifiant hors de l'URL est le même argument que pour toute décision entre clé API et jeton Bearer : les URL sont enregistrées, mises en cache et partagées.

Une autre distinction. Tout ce qui figure dans cet article concerne des données de catalogue en lecture seule, qui ne nécessitent que l'identifiant de l'application. L'API v4 ajoute des fonctionnalités de compte telles que les listes, les favoris, les évaluations et les listes de surveillance. L'écriture pour un utilisateur TMDB nécessite un échange supplémentaire : un jeton de demande de /4/auth/request_token, l'approbation de l'utilisateur, puis un jeton d'accès utilisateur de /4/auth/access_token. Rien de tout cela n'est nécessaire pour rechercher des films ou lire des détails.

Étape 3 : effectuez votre première requête

Tous les appels v3 sont dirigés vers https://api.themoviedb.org/3. Deux points de terminaison couvrent la plupart des premiers projets : recherche par titre, puis récupération des détails par ID.

Rechercher un film avec curl

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'

La réponse est un objet page avec page, results, total_pages et total_results. Chaque résultat contient id, title, release_date, overview, poster_path, genre_ids et vote_average. Dans l'exemple de recherche de TMDB, le premier résultat pour « fight club » a l'ID 550, sorti le 15-10-1999.

Le même appel avec la clé v3 ressemble à ceci. Notez qu'il n'y a pas d'en-tête d'authentification du tout :

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

Obtenir les détails d'un film avec Python

Prenez maintenant l'ID de la recherche et demandez l'enregistrement complet. Le point de terminaison des détails de film renvoie runtime, genres, budget, revenue et overview. Son paramètre append_to_response ajoute des sous-ressources telles que les crédits au même aller-retour, jusqu'à 20 par requête.

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"])

La dernière ligne est la partie que les gens oublient. poster_path n'est qu'un chemin. Comme l'guide des bases de l'image l'explique, une URL fonctionnelle est https://image.tmdb.org/t/p/, puis une taille telle que w500 ou original, puis le chemin. /3/configuration liste toutes les tailles valides.

Étape 4 : exécuter et enregistrer les requêtes dans Apidog

Une fois que les appels bruts fonctionnent, déplacez-les quelque part où vous ne les perdrez pas. Dans Apidog, cela prend quelques minutes et vous laisse avec un test enregistré et partageable.

1. Créez un projet et ajoutez un environnement appelé « TMDB » avec deux variables : base_url défini sur https://api.themoviedb.org/3, et tmdb_token contenant votre jeton d'accès en lecture. Marquez le jeton comme secret afin qu'il soit masqué dans l'interface utilisateur et exclu des exportations ; le guide sur les variables d'environnement et secrètes couvre les options.
2. Ajoutez une requête GET à {{base_url}}/search/movie avec un paramètre query. Dans l'onglet Auth, choisissez Bearer Token et entrez {{tmdb_token}}. Envoyez-la et confirmez que vous obtenez un 200 et un tableau results.
3. Ajoutez une deuxième requête GET à {{base_url}}/movie/{{movie_id}}. Dans le post-processeur de la première requête, extrayez results[0].id dans movie_id afin que le deuxième appel suive toujours le premier.
4. Enregistrez les deux comme scénario de test avec des assertions : le statut est égal à 200, total_results est supérieur à 0, et title dans la réponse des détails n'est pas vide. Exécutez-le chaque fois que l'intégration change.

Vous construisez une interface utilisateur (frontend) avec ces données ? Activez le serveur de maquette (mock server) pour le point de terminaison de recherche. Apidog génère une réponse correspondant au schéma, de sorte que l'équipe UI peut construire la grille d'affiches sans jeton en direct ni requêtes réelles contre les limites de TMDB.

Limites de débit et règles d'attribution

Tout ce qui suit est cité de la documentation de TMDB.

Limites de débit. La page sur les limites de débit de TMDB indique que la limite originale de 40 requêtes toutes les 10 secondes a été désactivée le 16 décembre 2019. Des plafonds subsistent « pour aider à atténuer le scraping de masse inutilement élevé », et ils « se situent quelque part autour de 40 requêtes par seconde ». Ce chiffre peut changer sans préavis, alors respectez tout code HTTP 429, patientez et réessayez.

Coût. De la FAQ : « Notre API est gratuite pour une utilisation non commerciale tant que vous attribuez TMDB comme source des données et/ou des images. » Les projets commerciaux doivent contacter sales@themoviedb.org.

Attribution. Affichez le logo TMDB et cette mention dans votre application : « Ce produit utilise l'API TMDB mais n'est ni approuvé ni certifié par TMDB. » Les conditions d'utilisation de l'API utilisent une formulation légèrement plus longue et exigent que le logo soit moins mis en évidence que votre propre marque, et qu'il ne soit jamais recoloré, étiré, retourné ou pivoté.

Mise en cache. Les conditions interdisent la mise en cache de toute donnée TMDB pendant plus de six mois. Stockez ce dont vous avez besoin, mais prévoyez un rafraîchissement.

Pas de SLA. TMDB le dit clairement. Intégrez des délais d'attente (timeouts) et des tentatives (retries).

Hygiène des clés. Les deux identifiants doivent être placés dans des variables d'environnement ou un gestionnaire de secrets, jamais dans le code source. Si l'un d'eux se retrouve dans un dépôt, faites-le pivoter depuis la page des paramètres et exécutez une vérification de fuite de clé API sur votre historique.

Erreurs courantes et leur signification

TMDB renvoie un corps JSON avec status_code et status_message en plus du statut HTTP. La référence des erreurs liste des dizaines de codes ; voici ceux que vous verrez en premier.

FAQ

La clé API TMDB est-elle gratuite ?

Oui, pour une utilisation non commerciale avec attribution. Il n'y a pas de niveau payant en libre-service. Si votre projet génère des revenus, TMDB vous demande d'organiser un accord commercial par l'intermédiaire de son équipe de vente.

Dois-je utiliser la clé API ou le jeton d'accès en lecture ?

Utilisez le jeton d'accès en lecture comme en-tête Bearer. TMDB le qualifie de par défaut, il fonctionne sur les versions v3 et v4, et il reste hors de vos URL. La clé v3 existe pour les outils qui ne peuvent envoyer que des paramètres de requête. Si le concept est nouveau, cette introduction sur ce qu'est une clé API explique le modèle que TMDB suit.

Puis-je appeler TMDB directement depuis un navigateur ou une application mobile ?

Vous le pouvez, mais tout ce qui est livré au client est public, y compris votre jeton. Pour un projet personnel, c'est un risque accepté. Pour tout ce qui implique des utilisateurs, placez un petit backend ou une fonction sans serveur devant TMDB, conservez le jeton là, et mettez en cache les requêtes populaires.

Quelle est la différence entre v3 et v4 ?

v3 est le catalogue : recherche, détails de films et de séries TV, personnes, images, découverte. v4 couvre les fonctionnalités de compte telles que les listes, les favoris, les évaluations et les listes de surveillance, et ses points de terminaison d'écriture nécessitent un jeton d'accès utilisateur. Votre jeton d'accès en lecture s'authentifie auprès des deux.

Que faire ensuite

Vous disposez maintenant d'une clé API TMDB fonctionnelle, d'une règle pour savoir quel identifiant envoyer, d'un flux de recherche-puis-détails en curl et Python, et du même flux enregistré comme scénario de test Apidog. Ensuite, ajoutez discover/movie pour la navigation filtrée et placez la mention d'attribution dans votre application avant de la partager. Tout le reste dans le catalogue utilise la même URL de base, le même en-tête Bearer et les mêmes formes d'erreur.