# API de métadonnées de films multilingue

> Cette API de métadonnées de films multilingue sert titres, résumés, slogans, noms de genres et biographies en 14 langues : anglais, russe, ukrainien, biélorusse, chinois, portugais, bulgare, hébreu, tchèque, roumain, français, polonais, italien et espagnol. Passez une balise TMDB comme ru-RU dans le paramètre language.

## Obtenir les données de films en 14 langues

`GET /3/movie/{movie_id}?language=ru-RU` renvoie le titre, le résumé, le slogan et les noms de genres en russe. Le paramètre `language` accepte les balises TMDB comme `ru-RU` ou `pt-BR` et fonctionne sur tous les points de terminaison qui renvoient du texte. Les identifiants restent les mêmes dans toutes les langues : une seule ligne de votre base de données les sert toutes.

Vous obtenez 14 langues avec une seule clé, l'`original_title` de chaque film, un point de terminaison de traductions qui liste toutes les langues d'un titre, et des noms de genres localisés. La liste complète est sur [langues](https://amodb.dev/fr/languages/).

## Les 14 langues servies

| Langue     | Code | Exemple de balise |
| ---------- | ---- | ----------------- |
| Anglais    | `en` | `en-US`           |
| Russe      | `ru` | `ru-RU`           |
| Ukrainien  | `uk` | `uk-UA`           |
| Biélorusse | `be` | `be-BY`           |
| Chinois    | `zh` | `zh-CN`           |
| Portugais  | `pt` | `pt-BR`           |
| Bulgare    | `bg` | `bg-BG`           |
| Hébreu     | `he` | `he-IL`           |
| Tchèque    | `cs` | `cs-CZ`           |
| Roumain    | `ro` | `ro-RO`           |
| Français   | `fr` | `fr-FR`           |
| Polonais   | `pl` | `pl-PL`           |
| Italien    | `it` | `it-IT`           |
| Espagnol   | `es` | `es-ES`           |

Toute autre balise se replie sur `en`. Le japonais et le coréen ne sont pas servis comme langues d'interface. Leurs titres originaux reviennent quand même dans `original_title` pour les films et `original_name` pour les séries.

## Les données obtenues

| Point de terminaison                       | Contenu localisé                                                           |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, noms de genres                             |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, noms de genres                              |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` et `overview` des saisons et des épisodes                           |
| `GET /3/person/{person_id}`                | `biography`                                                                |
| `GET /3/genre/movie/list`                  | Noms de genres pour les filtres et les menus                               |
| `GET /3/movie/{movie_id}/translations`     | Toutes les langues d'un titre en une seule réponse                         |
| `GET /3/movie/{movie_id}/images`           | Affiches étiquetées par langue, filtrées avec `include_image_language`     |
| `GET /3/movie/{movie_id}/videos`           | Vidéos étiquetées par `iso_639_1`, toutes les langues en une seule réponse |

## Démarrer en 3 étapes

1. Choisissez une offre sur les [tarifs](https://amodb.dev/fr/pricing/). Le nombre de langues ne change pas avec l'offre, seul le débit de requêtes change.
2. Créez une clé dans le tableau de bord de votre compte.
3. Appelez n'importe quel point de terminaison avec une balise `language`, et envoyez la clé dans `api_key` ou dans un en-tête Bearer.

## Exemple de requête

L'exemple bash affiche le titre de Fight Club (id `550`) en trois langues. Il utilise `jq` pour afficher un champ. L'exemple PHP demande le biélorusse et se replie sur l'anglais quand le résumé est vide.

```bash
for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done
```

```php
<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        throw new RuntimeException("amodb returned $status");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;
```

Réponse pour `language=ru-RU`, réduite à quelques champs. La clé `text_language` de l'exemple PHP est ajoutée par votre code, pas par l'API.

```json
{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}
```

## Repli quand un champ est vide

Tous les titres n'ont pas de texte dans toutes les langues. Un `overview` peut revenir vide quand il n'existe pas de traduction, et un `title` ou un `tagline` peut revenir en anglais. L'API n'invente pas de texte. Utilisez un ordre fixe pour que la page affiche toujours quelque chose :

1. Demandez la langue que vous affichez.
2. Si un champ est vide, demandez `en-US` pour le même identifiant, ou lisez l'entrée anglaise de la liste des traductions.
3. Si le titre est vide, affichez `original_title`.
4. Enregistrez la langue d'origine de chaque champ, pour pouvoir réessayer plus tard.

Le cache de périphérie conserve une copie par langue pour chaque chemin mis en cache : le repli en anglais d'un titre populaire est donc généralement servi depuis le cache.

## Lister toutes les traductions d'un titre

`GET /3/movie/{movie_id}/translations` renvoie un tableau `translations`, avec une entrée par langue disposant de données. La liste peut être plus longue que les 14 langues servies : Fight Club a 50 entrées. Utilisez-la pour construire un sélecteur de langue, ou pour stocker tous les textes d'un titre dans une seule ligne.

| Champ                                                                         | Signification                              |
| ----------------------------------------------------------------------------- | ------------------------------------------ |
| `iso_639_1`, `iso_3166_1`                                                     | Codes de langue et de pays                 |
| `english_name`                                                                | Nom de la langue en anglais                |
| `data.title` (films) ou `data.name` (séries), `data.overview`, `data.tagline` | Texte localisé, le titre peut être vide    |
| `data.homepage`, `data.runtime`                                               | Valeurs facultatives pour cette traduction |

Le même point de terminaison existe pour les séries et les épisodes. Les entrées de séries portent `data.name` et pas de `runtime`, et les entrées d'épisodes ne portent que `name` et `overview`. Les saisons répondent par une liste vide, et les personnes et les collections n'ont pas de point de terminaison de traductions. Les détails sont sur [traductions](https://amodb.dev/fr/translations/). Un seul appel de traductions remplace jusqu'à 14 appels de détails quand vous voulez toutes les langues à la fois.

## Affiches et vidéos par langue

Les images et les vidéos portent leurs propres balises de langue dans `iso_639_1`. Sur les points de terminaison d'images, passez une liste séparée par des virgules et ajoutez `null` pour les éléments sans langue, comme les affiches sans texte. La réponse contient les éléments correspondants, classez-les donc dans votre code.

| Paramètre                | Utilisé sur                    | Exemple      |
| ------------------------ | ------------------------------ | ------------ |
| `include_image_language` | Points de terminaison d'images | `ru,en,null` |

Les points de terminaison de vidéos renvoient toutes les langues en une seule réponse et ignorent `include_video_language` : filtrez donc vous-même sur `iso_639_1`. Voir [images](https://amodb.dev/fr/images-api/) pour les tailles et le CDN.

## L'hébreu et le texte de droite à gauche

L'hébreu est la seule langue de droite à gauche parmi les 14. Gérez-le dans la page, pas dans les données :

- Définissez `lang="he"` et `dir="rtl"` sur l'élément qui contient le texte.
- Entourez les titres en caractères latins au milieu d'un texte hébreu d'un élément `<bdi>` pour que la ponctuation ne passe pas du mauvais côté.
- Utilisez des propriétés CSS logiques comme `margin-inline-start` au lieu de gauche et droite.

## Comparaison

| Capacité                                 | Extraire les pages soi-même     | Jeu de données en anglais uniquement | amodb                                 |
| ---------------------------------------- | ------------------------------- | ------------------------------------ | ------------------------------------- |
| Langues                                  | Une langue de site par requête  | Anglais                              | 14 langues avec `language`            |
| Même identifiant dans toutes les langues | Des URL différentes par langue  | Sans objet                           | Le même identifiant numérique partout |
| Toutes les traductions d'un titre        | Récupérer chaque page de langue | Sans objet                           | Un seul appel `translations`          |
| Affiches localisées                      | URL d'images par langue         | Voir leur documentation              | Filtre `include_image_language`       |
| Titre original                           | À extraire du texte de la page  | Voir leur documentation              | `original_title`, `original_name`     |

## Tarifs

Le jeu de langues est le même pour toutes les offres : vous ne payez donc que le débit et la période. Achetez 1, 3, 6, 12 ou 24 mois prépayés, avec 0, 10, 20, 30 ou 40 pour cent de réduction sur les plus longues et sans renouvellement automatique. Les offres à 20, 40 et 120 requêtes par minute incluent toutes les langues et tous les points de terminaison. Un site en cinq langues demande jusqu'à cinq appels de détails par titre, et les requêtes répétées sont servies depuis le cache de périphérie pendant 6 heures. Pas d'offre gratuite. Voir les [tarifs](https://amodb.dev/fr/pricing/).

## Questions et réponses

### Quelles langues l'API sert-elle ?

Quatorze : anglais, russe, ukrainien, biélorusse, chinois, portugais, bulgare, hébreu, tchèque, roumain, français, polonais, italien et espagnol, avec les codes en ru uk be zh pt bg he cs ro fr pl it es.

### Que se passe-t-il si j'envoie une balise de langue qui n'est pas servie ?

La réponse se replie sur l'anglais. Une balise comme ja-JP renvoie du texte anglais, tandis que le titre japonais d'origine arrive quand même dans original_title pour les films et original_name pour les séries.

### Puis-je obtenir toutes les traductions d'un titre en une seule requête ?

Oui. GET /3/movie/{movie_id}/translations liste une entrée par langue disposant de données, chacune avec title, overview, tagline, homepage et runtime. Les séries et les épisodes ont le même point de terminaison, avec name à la place de title. Les saisons, les personnes et les collections n'ont pas de traductions.

### Comment gérer un résumé manquant dans la langue choisie ?

Testez la chaîne vide, puis demandez le même identifiant avec en-US, ou lisez l'entrée anglaise de la liste des traductions. Affichez original_title en dernier repli et signalez que le texte est en anglais. Les titres et les slogans peuvent déjà revenir en anglais.

### Les affiches sont-elles localisées aussi ?

Les affiches portent une balise de langue. Demandez-les avec include_image_language, par exemple ru,en,null, et classez les correspondances dans votre code. Les fichiers d'images viennent de img.amodb.dev et n'exigent aucune clé.

## Pages liées

- [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.
- [API des traductions](https://amodb.dev/fr/translations/): API de traductions aux chemins TMDB v3 : lisez titres, résumés et slogans d'un film, d'une série ou d'un épisode dans toutes ses langues à la fois.
- [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.
- [API d'images et hôte d'images](https://amodb.dev/fr/images-api/): API d'images de films aux chemins TMDB v3 : listez affiches, fonds, logos et images par titre, puis chargez-les depuis img.amodb.dev en 10 tailles sans clé.
- [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/multilingual-movie-metadata-api/