API de bandes-annonces de films

L'API de bandes-annonces est GET /3/movie/{movie_id}/videos sur api.amodb.dev. Chaque vidéo porte un type, un indicateur officiel, une langue et une date de publication, ce qui permet de choisir la bande-annonce officielle en un seul passage. Les séries renvoient la même forme. Chemins et JSON suivent TMDB v3.

Voir les offres Lire le démarrage rapide

Requête

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"

const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');

Réponse 200

{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"

Obtenir la bande-annonce officielle d'un film

GET /3/movie/{movie_id}/videos renvoie toutes les vidéos associées à un film. Chaque élément a un type, un indicateur official, un code de langue, un horodatage published_at, ainsi que le site et la key qui identifient la vidéo. Gardez les éléments dont type vaut Trailer et official vaut true, et vous avez votre bande-annonce.

Vous obtenez une liste de fiches vidéo que vous classez vous-même, pas un flux. La réponse nomme la vidéo et indique où elle se trouve, et votre page construit le lecteur à partir de site et key. La même forme revient pour les séries. Les chemins de saisons et d'épisodes répondent par une liste vide.

Les données obtenues

Point de terminaison	Renvoie
`GET /3/movie/{movie_id}/videos`	Bandes-annonces, teasers, extraits, making of, coulisses et bêtisiers d'un film
`GET /3/tv/{tv_id}/videos`	La même liste pour une série
`GET /3/tv/{tv_id}/season/{season_number}/videos`	Toujours une liste `results` vide
`GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos`	Toujours une liste `results` vide
`GET /3/movie/{movie_id}` avec `append_to_response=videos`	Les détails et les vidéos en une seule requête

Champs de chaque vidéo :

Champ	Type	Usage
`type`	chaîne	Genre de vidéo : `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` ou `Bloopers`, comme sur la page des vidéos
`official`	booléen	`true` quand la vidéo est signalée comme officielle
`iso_639_1`, `iso_3166_1`	chaîne	Codes de langue et de pays de la vidéo
`key`, `site`	chaîne	Identifiant de la vidéo et nom du site qui l'héberge, `YouTube` sur toutes les vidéos vues
`size`	entier	Résolution verticale, `1080` sur toutes les vidéos vues
`published_at`	chaîne	Horodatage ISO 8601, pratique pour un tri du plus récent au plus ancien
`name`, `id`	chaîne	Titre de la vidéo et son id, qui est la même chaîne que `key`

Démarrer en 3 étapes

Choisissez une offre sur les tarifs. Chaque offre renvoie toutes les données : vous choisissez donc selon les requêtes par minute.
Créez une clé dans le tableau de bord de votre compte. Elle fait 32 caractères hexadécimaux en minuscules.
Appelez GET /3/movie/{movie_id}/videos avec la clé dans api_key ou dans un en-tête Authorization: Bearer.

Exemple de requête

L'exemple demande les vidéos d'Inception (id 27205), les classe dans le code et affiche la meilleure. Le classement place d'abord les correspondances de langue, puis Trailer avant Teaser, puis les officielles avant les non officielles, puis le published_at le plus récent.

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"

const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');

Réponse abrégée : les 2 premières des 42 vidéos. La liste contient toutes les langues.

JSON

{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"
    },
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "35mm Theatrical Trailer #3",
      "key": "cdx31ak4KbQ",
      "site": "YouTube",
      "size": 1080,
      "type": "Trailer",
      "official": false,
      "published_at": "2022-03-07T06:00:19Z",
      "id": "cdx31ak4KbQ"
    }
  ]
}

Choisir la vidéo à lire

Un titre a souvent plusieurs bandes-annonces officielles (une première annonce, une version finale) à côté de teasers et d'extraits. Classez-les dans un ordre fixe pour que la page ne se retrouve jamais avec un bêtisier à la place de la bande-annonce.

Priorité	Filtre	Usage typique
1	`Trailer`, officielle, langue correspondante	La vidéo à lire
2	`Trailer`, non officielle	Envois régionaux ou de fans quand rien d'officiel n'existe
3	`Teaser`, officiel	Courts spots avant la sortie
4	`Clip`, `Featurette`	Solution de repli pour que l'emplacement ne soit pas vide
à ignorer	`Behind the Scenes`, `Bloopers`	À montrer dans une liste d'extras séparée

Départagez les égalités par published_at. Du plus récent au plus ancien donne la dernière version, du plus ancien au plus récent donne la première annonce.

Langues des bandes-annonces

Les vidéos sont étiquetées avec une langue via iso_639_1, et un titre peut avoir des bandes-annonces dans plusieurs. Inception a 42 vidéos en 9 langues. amodb les renvoie toutes en une réponse. Les paramètres language et include_video_language n'ont aucun effet sur les points de terminaison de vidéos : choisissez donc la langue dans votre code.

Étape	Que faire
1	Garder les vidéos dont `iso_639_1` correspond à votre utilisateur, par exemple `ru`
2	Si aucune ne correspond, garder `en`
3	Si aucune ne correspond, garder le reste

Classez à l'intérieur de chaque étape par type et par indicateur official, comme dans l'exemple. Les langues des vidéos suivent l'envoi et non les 14 langues d'interface listées sur langues : une bande-annonce peut donc être en cs ou en he.

Bandes-annonces des séries

La bande-annonce d'une série se trouve sur /3/tv/1396/videos (Breaking Bad), qui contient 9 bandes-annonces. La fonction de classement ci-dessus fonctionne telle quelle, car les champs ne changent pas. Les chemins de saisons et d'épisodes comme /3/tv/1396/season/1/videos répondent 200 avec une liste results vide : lisez donc la liste de la série. Voir vidéos et bandes-annonces pour la liste complète des chemins.

Construire un carrousel de bandes-annonces

Un carrousel de films à l'affiche demande un appel de liste et un appel par titre : GET /3/movie/now_playing (voir tendances et listes) plus dix appels de vidéos font 11 requêtes pour dix titres. Stockez la key choisie à côté de l'identifiant du film. Les bandes-annonces changent rarement : actualisez un choix stocké toutes les quelques heures ou quand un titre ressort.

Comparaison

Capacité	Extraire les pages soi-même	API de métadonnées avec offre gratuite	amodb
Indicateur officiel	Deviner à partir du titre de la page	Voir leur documentation	Booléen `official` sur chaque vidéo
Filtre par type de vidéo	Analyser du texte	Voir leur documentation	Six valeurs de `type`
Choix de la langue	Une langue par page	Voir leur documentation	`iso_639_1` et `iso_3166_1` sur chaque vidéo, filtrés dans votre code
Séries et épisodes	Des pages séparées à parcourir	Voir leur documentation	Les séries utilisent le même point de terminaison, les listes de saisons et d'épisodes sont vides
Entretien	Casse quand le balisage change	Dépend du fournisseur	Une seule forme JSON stable
Conditions	Vous portez le risque	Voir leurs conditions	Offres payantes, voir les tarifs

Tarifs

Les offres sont prépayées. Vous achetez 1, 3, 6, 12 ou 24 mois et obtenez 0, 10, 20, 30 ou 40 pour cent de réduction pour les périodes plus longues. Rien ne se renouvelle tout seul. Les offres à 20, 40 et 120 requêtes par minute servent toutes tous les points de terminaison de cette page : un carrousel de bandes-annonces très sollicité est donc une question de débit uniquement. Il n'y a ni offre gratuite ni essai. Comparez les offres sur les tarifs.

Questions et réponses

Comment obtenir la bande-annonce officielle d'un film ?

Appelez GET /3/movie/{movie_id}/videos, gardez les éléments dont type vaut Trailer et official vaut true, puis triez par published_at. Le premier élément est la bande-annonce officielle la plus récente. S'il n'existe aucune bande-annonce, repliez-vous sur un Teaser.

L'API renvoie-t-elle un fichier vidéo ou un flux ?

Non. Elle renvoie les métadonnées de chaque vidéo : name, type, site, key, size, language et dates. Vous construisez le lien du lecteur à partir de site et key, ou vous intégrez la vidéo dans votre propre page. Les affiches et les images viennent de img.amodb.dev.

Comment obtenir les bandes-annonces dans ma langue ?

Le point de terminaison videos renvoie toutes les langues en une réponse et ignore les paramètres language et include_video_language. Filtrez sur iso_639_1 dans votre code, par exemple ru d'abord, puis en, puis le reste. Inception contient des vidéos en 9 langues.

Puis-je obtenir les bandes-annonces des séries et des épisodes ?

Pour les séries, oui : utilisez /3/tv/{tv_id}/videos. Les champs sont les mêmes, donc le code de classement écrit pour les films fonctionne sans changement. Les chemins de vidéos de saisons et d'épisodes répondent par un tableau results vide : utilisez la liste de la série.

Combien de requêtes une recherche de bande-annonce utilise-t-elle ?

Une requête par titre. Avec append_to_response=videos, la bande-annonce arrive dans l'appel de détails : détails plus bande-annonce restent donc une seule requête sur vos 20, 40 ou 120 requêtes par minute.

Mis à jour le 18 oct. 2026

Voir en Markdown