# 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.

## 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

1. Choisissez une offre sur les [tarifs](https://amodb.dev/fr/pricing/). Chaque offre renvoie toutes les données : vous choisissez donc selon les requêtes par minute.
2. Créez une clé dans le tableau de bord de votre compte. Elle fait 32 caractères hexadécimaux en minuscules.
3. 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.

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

```js
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](https://amodb.dev/fr/languages/) : 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](https://amodb.dev/fr/videos-trailers/) 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](https://amodb.dev/fr/trending-lists/)) 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](https://amodb.dev/fr/pricing/)                                 |

## 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](https://amodb.dev/fr/pricing/).

## 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.

## Pages liées

- [API des vidéos et bandes-annonces](https://amodb.dev/fr/videos-trailers/): API de vidéos aux chemins TMDB v3 : listez bandes-annonces, teasers, extraits et making of d'un film ou d'une série, puis filtrez par type et langue.
- [API de détails de film](https://amodb.dev/fr/movies/): API de détails de film aux chemins et au JSON de TMDB v3. Obtenez un film par id, ajoutez crédits, notes et ambiances avec append_to_response, en 14 langues.
- [API des séries TV](https://amodb.dev/fr/tv-series/): API de séries TV aux chemins et au JSON de TMDB v3 : une série par id avec saisons, chaînes et prochain épisode, plus classifications et plateformes.
- [Tendances et points de terminaison de listes](https://amodb.dev/fr/trending-lists/): API de tendances aux chemins TMDB v3 : classements jour et semaine, plus films et séries à l'affiche, populaires, mieux notés et à venir, cache de 30 minutes.
- [Langues](https://amodb.dev/fr/languages/): amodb sert titres, résumés et noms en 14 langues. Passez une balise TMDB comme ru-RU ou pt-BR dans language ; toute autre balise se replie sur l'anglais.
- [Démarrage rapide](https://amodb.dev/fr/quickstart/): Faites votre premier appel amodb : obtenez une clé, demandez un film en curl, JavaScript, Python, PHP ou Go, puis chargez l'affiche. En moins de 2 minutes.

Mis à jour: 2026-10-18. Source: https://amodb.dev/fr/movie-trailer-api/