# API d'affiches de films et CDN d'images

> Les affiches se chargent depuis https://img.amodb.dev/t/p/{size}/{file} sans clé d'API. La partie file est le poster_path de n'importe quelle réponse de film, de recherche ou de liste. Les noms de taille vont de w92 à original, et include_image_language choisit les affiches par langue. Seuls les appels JSON demandent votre clé.

## Des affiches de films depuis un hôte d'images sans clé

L'URL d'une affiche est `https://img.amodb.dev/t/p/{size}/{file}`. La partie file est la chaîne `poster_path` de n'importe quelle réponse de film, de recherche ou de liste, et elle commence par une barre oblique. La partie taille est un nom comme `w342`. Les images n'exigent aucune clé, donc les navigateurs et les applications peuvent les charger directement. Le JSON qui vous donne le nom du fichier exige toujours votre clé, et amodb est une API indépendante qui parle le protocole TMDB v3 : le code d'images existant continue de fonctionner après un changement d'hôte.

Ce que vous obtenez :

- Des affiches, des images de fond, des logos, des photos de profil et des images d'épisodes sur un seul hôte.
- Dix noms de taille, de `w92` à `original`.
- Des listes d'affiches par titre, avec la langue, la largeur et la hauteur de chaque élément.
- Un cache de périphérie de 30 jours pour les images.

## Les données obtenues

| Image                          | Le nom du fichier vient de                                 | Tailles courantes                                         |
| ------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------- |
| Affiche de film                | `poster_path` sur `/3/movie/{movie_id}` et dans les listes | `w92`, `w154`, `w185`, `w342`, `w500`, `w780`, `original` |
| Image de fond                  | `backdrop_path`                                            | `w300`, `w780`, `w1280`, `original`                       |
| Photo de personne              | `profile_path` sur `/3/person/{person_id}`                 | `w185`, `h632`, `original`                                |
| Logo de société ou de chaîne   | `logo_path`                                                | `w92`, `w154`, `w185`, `w300`, `w500`, `original`         |
| Image d'épisode                | `still_path`                                               | `w92`, `w185`, `w300`, `original`                         |
| Toutes les affiches d'un titre | `GET /3/movie/{movie_id}/images`                           | Tableau `posters`                                         |

Les séries, les saisons et les collections portent aussi `poster_path`. Lisez une fois au démarrage les listes de tailles exactes dans le bloc `images` de `GET /3/configuration` au lieu de les écrire en dur. La référence des images est sur [images](https://amodb.dev/fr/images-api/).

## Démarrer en 3 étapes

1. Choisissez une offre sur les [tarifs](https://amodb.dev/fr/pricing/). Elle fixe le débit des appels JSON : 20, 40 ou 120 requêtes par minute.
2. Créez une clé dans le tableau de bord de votre compte.
3. Lisez `poster_path` dans un appel de détails ou de liste, puis placez-le derrière l'hôte d'images et un nom de taille.

## Exemple de requête

Le programme Go liste les affiches de The Matrix (id de film 603) en anglais et sans texte, choisit la plus large, affiche un `srcset` prêt à l'emploi et enregistre le fichier `w342`. La clé ne sert qu'à l'appel JSON.

```bash
# the JSON call needs the key
curl -s "https://api.amodb.dev/3/movie/603/images?include_image_language=en,null" \
  -H "Authorization: Bearer $AMODB_KEY"

# the image call does not
curl -s -o poster.jpg "https://img.amodb.dev/t/p/w342/aOIuZAjPaRIE6CMzbazvcHuHXDc.jpg"
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
	"time"
)

const imgBase = "https://img.amodb.dev/t/p/"

type poster struct {
	FilePath string  `json:"file_path"`
	Lang     *string `json:"iso_639_1"`
	Width    int     `json:"width"`
}

type images struct {
	Posters []poster `json:"posters"`
}

func srcset(file string) string {
	var parts []string
	for _, w := range []int{185, 342, 500, 780} {
		parts = append(parts, fmt.Sprintf("%sw%d%s %dw", imgBase, w, file, w))
	}
	return strings.Join(parts, ", ")
}

func main() {
	client := &http.Client{Timeout: 10 * time.Second}

	url := "https://api.amodb.dev/3/movie/603/images?include_image_language=en,null"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}

	var imgs images
	if err := json.NewDecoder(res.Body).Decode(&imgs); err != nil {
		panic(err)
	}
	if len(imgs.Posters) == 0 {
		fmt.Println("no posters")
		return
	}

	best := imgs.Posters[0]
	for _, p := range imgs.Posters {
		if p.Width > best.Width {
			best = p
		}
	}
	lang := "none"
	if best.Lang != nil {
		lang = *best.Lang
	}
	fmt.Println("best poster:", best.FilePath, "language:", lang, "width:", best.Width)
	fmt.Println("srcset:", srcset(best.FilePath))

	// Image requests carry no key.
	pic, err := client.Get(imgBase + "w342" + best.FilePath)
	if err != nil {
		panic(err)
	}
	defer pic.Body.Close()
	if pic.StatusCode != http.StatusOK {
		panic(pic.Status)
	}
	out, err := os.Create("poster.jpg")
	if err != nil {
		panic(err)
	}
	defer out.Close()
	io.Copy(out, pic.Body)
}
```

Une réponse d'images abrégée pour `include_image_language=en,null` : 3 des 145 affiches, une anglaise, la plus large des anglaises et une sans texte. La réponse contient aussi `backdrops` et `logos`, omis ici.

```json
{
  "id": 603,
  "posters": [
    {
      "aspect_ratio": 0.667,
      "height": 2250,
      "iso_639_1": "en",
      "file_path": "/dXNAPwY7VrqMAo51EKhhCJfaGb5.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 1500
    },
    {
      "aspect_ratio": 0.667,
      "height": 3000,
      "iso_639_1": "en",
      "file_path": "/aOIuZAjPaRIE6CMzbazvcHuHXDc.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 2000
    },
    {
      "aspect_ratio": 0.701,
      "height": 1426,
      "iso_639_1": null,
      "file_path": "/iLWzJxatuwwMT76dtMuwh3FEp2X.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 1000
    }
  ]
}
```

## Choisir une taille

Le nombre dans une taille `w` est la largeur de l'image en pixels, et `h632` est une hauteur. Les petits noms économisent de la bande passante, les grands gardent le détail sur les écrans denses.

| Taille         | Usage typique                                              |
| -------------- | ---------------------------------------------------------- |
| `w92`          | Suggestions de recherche et toutes petites lignes de liste |
| `w154`, `w185` | Listes denses et cartes                                    |
| `w342`         | Vignettes de grille sur téléphone                          |
| `w500`         | Page de détails                                            |
| `w780`         | Grands écrans et écrans 2x                                 |
| `original`     | Archive ou impression, le fichier sans redimensionnement   |

Donnez plusieurs largeurs au navigateur et laissez-le choisir. Le programme Go ci-dessus affiche un `srcset` avec des candidats `185w`, `342w`, `500w` et `780w`. Associez-le à un attribut `sizes` qui correspond à votre mise en page, par exemple `sizes="(max-width: 600px) 45vw, 185px"` sur l'élément `img`.

## Langues des affiches

Chaque élément de `posters` a une valeur `iso_639_1`, soit un code de langue, soit null pour un visuel sans texte. Le paramètre `include_image_language` accepte une liste de codes séparés par des virgules.

| Valeur    | Renvoie                                            |
| --------- | -------------------------------------------------- |
| `en`      | Les affiches marquées en anglais                   |
| `en,null` | Les affiches en anglais et les affiches sans texte |
| `null`    | Uniquement les affiches sans texte                 |

Un bon ordre de repli est l'affiche dans la langue de l'utilisateur, puis une affiche sans texte, puis l'anglais. Dans chaque groupe, triez par `width` et gardez la première en cas d'égalité. `vote_average` et `vote_count` valent `0` sur les images de films et de séries, donc ils ne classent rien. Les langues des affiches décrivent le texte imprimé sur le visuel et ne suivent donc pas les 14 langues d'interface. Vérifiez `iso_639_1` sur ce qui revient, car l'ensemble dépend du titre.

## Stocker et mettre en cache les affiches

- Enregistrez `poster_path` et non l'URL complète. Toute taille peut en être construite plus tard.
- La périphérie met les images en cache 30 jours. Les détails sont mis en cache 6 heures : relisez donc `poster_path` après ce délai pour voir s'il a changé.
- Gardez la clé sur votre serveur. N'envoyez au navigateur que les URL d'images.
- Quand `poster_path` est null, affichez une image de remplacement plutôt qu'une image cassée.

## Comparaison

| Capacité                   | Extraire les images des pages                      | Héberger vos propres copies     | Hôte d'images amodb                                             |
| -------------------------- | -------------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
| Clé nécessaire             | Aucune, les conditions de chaque site s'appliquent | Aucune                          | Aucune clé pour les images                                      |
| Variantes de taille        | La taille que sert la page                         | Vous générez et stockez chacune | Noms de taille fixes dans l'URL, de `w92` à `original`          |
| Trouver le fichier         | Analyser le HTML                                   | Votre propre base de données    | `poster_path` dans chaque réponse                               |
| Langues des visuels        | Page par page                                      | Ce que vous avez collecté       | `include_image_language` sur les points de terminaison d'images |
| Stockage et bande passante | Les vôtres, plus ceux de la source                 | Les vôtres                      | Le navigateur charge depuis `img.amodb.dev`                     |
| Cache                      | Le vôtre                                           | Le vôtre                        | 30 jours en périphérie                                          |

## Tarifs

Le téléchargement des images ne demande aucune clé. Votre offre ne limite que les appels JSON qui vous donnent les noms de fichiers, et les réponses de liste incluent déjà `poster_path` pour chaque élément : un seul appel de liste alimente donc toute une grille. Choisissez 20, 40 ou 120 requêtes par minute sur les [tarifs](https://amodb.dev/fr/pricing/). L'accès est prépayé pour 1, 3, 6, 12 ou 24 mois avec 0, 10, 20, 30 et 40 pour cent de réduction, rien ne se renouvelle tout seul, et il n'y a pas d'offre gratuite.

## Questions et réponses

### Le téléchargement des affiches exige-t-il une clé d'API ?

Non. Les images viennent de https://img.amodb.dev/t/p/{size}/{file} sans clé, donc un navigateur peut les charger directement. Seuls les appels JSON qui renvoient poster_path utilisent votre clé.

### Quelles tailles d'affiches sont disponibles ?

Les noms de taille sont w92, w154, w185, w300, w342, w500, w780, w1280, h632 et original. Celles qui conviennent à un type d'image figurent dans le bloc images de GET /3/configuration.

### Comment obtenir une affiche dans une langue donnée ?

Appelez /3/movie/{id}/images?include_image_language=en,null et lisez iso_639_1 sur chaque affiche. La valeur null marque un visuel sans texte. Choisissez ensuite par largeur. vote_average et vote_count valent 0 sur les images de films et de séries.

### Combien de temps les images sont-elles mises en cache ?

La périphérie conserve les images 30 jours. Stockez la valeur de poster_path et non l'URL complète, afin de pouvoir construire plus tard n'importe quelle autre taille sans nouvelle recherche.

### Que montrer quand poster_path vaut null ?

Certains titres n'ont pas d'affiche. Montrez une image de remplacement issue de votre propre design et, si vous le souhaitez, appelez le point de terminaison images pour chercher d'autres affiches avant d'abandonner.

## Pages liées

- [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é.
- [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 de recherche](https://amodb.dev/fr/search/): API de recherche aux chemins et au JSON de TMDB v3 : films, séries, personnes, collections, sociétés et mots-clés par texte, filtres d'année et pagination.
- [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.
- [Authentification](https://amodb.dev/fr/authentication/): Comment envoyer votre clé amodb : api_key dans la requête, en-tête Authorization Bearer, ou apikey pour OMDb. Format, stockage, rotation et erreurs 401.

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