# API des saisons et épisodes de séries TV > Lisez une saison avec tous ses épisodes sur GET /3/tv/{series_id}/season/{season_number}, ou un seul épisode un niveau plus bas. Le JSON suit TMDB v3 avec air_date, episode_number, runtime et still_path. Chaque épisode porte crew et guest_stars, la saison 0 contient les épisodes spéciaux, et append_to_response ajoute crédits, images et vidéos. ## Point de terminaison `GET /3/tv/{series_id}/season/{season_number}` ```bash curl "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to team up with a former student and create a top of the line crystal meth in a used RV, to provide for his family once he is gone.", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7029219c29533d00dd2c1", "adult": false, "gender": 2, "id": 2483, "known_for_department": "Camera", "name": "约翰·托尔", "original_name": "约翰·托尔", "popularity": 1.1957, "profile_path": "/cfL9A6tC7L5Ps5fq1o3WpVKGMb1.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee313280006e8", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Jock", "credit_id": "52542275760ee313280006b4", "order": 500, "adult": false, "gender": 2, "id": 1216132, "known_for_department": "Acting", "name": "Aaron Hill", "original_name": "Aaron Hill", "popularity": 1.6521, "profile_path": "/rNp31SeoVqSQU6OZWxZUhGwAgyq.jpg" }, { "character": "Dr. Belknap", "credit_id": "52725cb1760ee3044d0b9984", "order": 502, "adult": false, "gender": 2, "id": 161591, "known_for_department": "Acting", "name": "Gregory Chase", "original_name": "Gregory Chase", "popularity": 0.5435, "profile_path": "/gNdodev00CROpXuAh5EFmkWTVOo.jpg" } ] }, { "air_date": "2008-01-27", "episode_number": 2, "episode_type": "standard", "id": 62086, "name": "Cat's in the Bag...", "overview": "Walt and Jesse attempt to tie up loose ends. The desperate situation gets more complicated with the flip of a coin. Walt's wife, Skyler, becomes suspicious of Walt's strange behavior.", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/AbMoecO0ZZio0LcgeLxlzdyGs6X.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Ob-Gyn", "credit_id": "63012c9c5f4b73008267ba53", "order": 682, "adult": false, "gender": 0, "id": 1448105, "known_for_department": "Acting", "name": "Shane Marinson", "original_name": "Shane Marinson", "popularity": 0, "profile_path": null }, { "character": "Ben", "credit_id": "63012d2111c066007cbc37b1", "order": 683, "adult": false, "gender": 0, "id": 3670897, "known_for_department": "Acting", "name": "Jason Byrd", "original_name": "Jason Byrd", "popularity": 0, "profile_path": null } ] }, { "air_date": "2008-02-10", "episode_number": 3, "episode_type": "standard", "id": 62087, "name": "...And the Bag's in the River", "overview": "Walter fights with Jesse over his drug use, causing him to leave Walter alone with their captive, Krazy-8. Meanwhile, Hank has a scared straight moment with Walter Jr. after his aunt discovers he has been smoking pot. Also, Skylar is upset...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/2kBeBlxGqBOdWlKwzAxiwkfU5on.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Carmen Molina", "credit_id": "52542273760ee31328000676", "order": 643, "adult": false, "gender": 1, "id": 115688, "known_for_department": "Acting", "name": "卡门·塞兰诺", "original_name": "卡门·塞兰诺", "popularity": 1.1342, "profile_path": "/nzJEe2UqvvMIBJZP1aeFEj4EunN.jpg" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Obtenir une saison `GET /3/tv/{series_id}/season/{season_number}` renvoie une saison et son tableau `episodes` complet en une seule réponse. Les numéros de saison commencent à `1`, et `0` est réservé aux épisodes spéciaux. Prenez l'identifiant de la série et les numéros de saison dans la fiche [séries TV](https://amodb.dev/fr/tv-series/). L'exemple lit la saison 1 de Breaking Bad. Le code affiche une ligne par épisode. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/tv/1396/season/1?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const season = await res.json(); for (const ep of season.episodes) { console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396/season/1", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() season = r.json() for ep in season["episodes"]: print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?") ``` ```php 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"); } $season = json_decode($body, true); foreach ($season['episodes'] as $ep) { printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Season struct { Name string `json:"name"` Episodes []struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` } `json:"episodes"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?language=en-US", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var s Season if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } for _, e := range s.Episodes { fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime) } } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | -------------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------- | | `series_id` | chemin | oui | Identifiant numérique de la série, par exemple `1396`. | | `season_number` | chemin | oui | Numéro de saison entier. `0` renvoie les épisodes spéciaux. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | | `language` | requête | non | Balise TMDB comme `en-US` ou `fr-FR`. 14 langues de base sont servies. Par défaut `en-US`. | | `append_to_response` | requête | non | Valeurs au niveau de la saison : `credits`, `external_ids`, `images`, `videos`. Les autres noms sont ignorés. | ### Champs de la réponse | Champ | Type | Remarques | | --------------------- | -------------- | ------------------------------------------------------------------- | | `id`, `season_number` | entier | Identifiant de la saison et son numéro dans la série. | | `name`, `overview` | chaîne | Texte localisé, vide quand il n'existe pas de traduction. | | `air_date` | chaîne ou null | Date du premier épisode, `YYYY-MM-DD`. | | `poster_path` | chaîne ou null | À ajouter à `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | nombre | Note agrégée des utilisateurs pour la saison. | | `episodes` | tableau | Tous les épisodes, avec les champs listés dans la section suivante. | ### Exemple de réponse `GET /3/tv/1396/season/1?language=en-US`. La saison compte 7 épisodes : `episodes` est donc réduit à une entrée, et les tableaux `crew` et `guest_stars` de cette entrée sont omis : ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0 } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` Chaque épisode de la réponse de saison porte aussi des tableaux `crew` et `guest_stars`, avec la forme d'entrée décrite sur [crédits](https://amodb.dev/fr/credits/). `runtime` peut être null pour un épisode pas encore diffusé. ## Obtenir un épisode `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` renvoie un épisode. La réponse de saison contient déjà tous les épisodes avec `crew` et `guest_stars` : utilisez donc ce point de terminaison pour actualiser une fiche sans recharger la saison. Il accepte `language` et `append_to_response` avec `credits`, `external_ids`, `images`, `translations` et `videos`. Une requête comme `/3/tv/1396/season/1/episode/1?append_to_response=credits` coûte une requête. | Champ | Type | Remarques | | --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | entier | Identifiant de l'épisode. | | `show_id` | entier | Identifiant de la série. Présent dans la réponse de saison et dans les pointeurs de série, pas dans la réponse d'un seul épisode. | | `season_number`, `episode_number` | entier | Position dans la série. Utilisez-les pour construire le chemin de la requête. | | `name`, `overview` | chaîne | Texte localisé. | | `air_date` | chaîne ou null | Date seule, sans heure ni fuseau horaire. Null quand non programmé. | | `episode_type` | chaîne | `standard` pour les épisodes normaux. Pour repérer un final, comparez `episode_number` avec l'`episode_count` de cette saison dans la fiche de la série. | | `runtime` | entier ou null | Minutes. | | `production_code` | chaîne | Code du studio, souvent vide. | | `still_path` | chaîne ou null | Image de l'épisode. Utilisez `w300` ou `original` depuis `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | nombre, entier | Note agrégée des utilisateurs. | | `crew`, `guest_stars` | tableau | Crédits de cet épisode, voir [crédits](https://amodb.dev/fr/credits/). | ## Prochain et dernier épisode dans la fiche de la série Le point de terminaison de série renvoie `next_episode_to_air` et `last_episode_to_air`. Chacun est un résumé d'épisode avec les champs ci-dessus, plus `show_id` et sans `crew` ni `guest_stars`. Le prochain est null pour les séries terminées et pour les séries en cours sans date confirmée. L'exemple lit South Park, une série en cours. ```js const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const next = (await res.json()).next_episode_to_air; console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode'); ``` Pour un compte à rebours, comparez `air_date` avec la date locale du spectateur. La valeur ne porte pas d'heure : affichez donc une date et non une heure d'horloge. ## Sous-ressources des saisons et des épisodes Les chemins de saisons et d'épisodes ont leurs propres sous-ressources. Plusieurs renvoient aujourd'hui des données vides. | Méthode et chemin | Renvoie | | --------------------------------------------------------- | ---------------------------------------------------------------------- | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` et `crew` de la saison | | `GET /tv/{series_id}/season/{season_number}/images` | `id` et un tableau `posters` vide | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` et un tableau `results` vide | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` plus `tvdb_id`, `wikidata_id` et d'autres identifiants, tous nuls | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` et un tableau `translations` vide | | `GET .../episode/{episode_number}/credits` | `id`, un `cast` vide, `crew` et `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` et un tableau `stills` avec l'image de l'épisode | | `GET .../episode/{episode_number}/videos` | `id` et un tableau `results` vide | | `GET .../episode/{episode_number}/external_ids` | `id` plus `imdb_id`, `tvdb_id` et d'autres identifiants, tous nuls | | `GET .../episode/{episode_number}/translations` | `id` et un tableau `translations` avec nom et résumé par langue | Les crédits de saisons et d'épisodes sont traités sur [crédits](https://amodb.dev/fr/credits/), et les images sur [images](https://amodb.dev/fr/images-api/). amodb ne propose pas les chemins `changes` de TMDB ni de point de terminaison pour les épisodes d'un groupe d'épisodes. ## Erreurs | HTTP | status_code | Quand | | ---- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 404 | 34 | La série, la saison ou l'épisode n'existe pas, par exemple la saison `0` d'une série sans épisodes spéciaux, ou le chemin n'est pas proposé. | | 405 | 37 | Vous avez appelé une méthode d'écriture. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | Voir [erreurs](https://amodb.dev/fr/errors/) pour le format complet du corps et [limites de débit](https://amodb.dev/fr/rate-limits/) pour les fenêtres. ## Remarques pratiques - Les saisons et les épisodes sont mis en cache 6 heures. Relisez la saison en cours une ou deux fois par jour pendant la diffusion d'une série. - Une série de 10 saisons demande 10 appels de saison. Avec l'offre à 20 requêtes par minute, cela utilise la moitié du quota d'une minute, et une seconde exécution dans les 6 heures est servie depuis le cache de périphérie. - Un épisode non diffusé peut avoir un `air_date` null, un `runtime` null et un `overview` vide. Affichez une image de remplacement au lieu d'échouer. - Les images d'épisodes sont des plans larges, pas des affiches. Demandez `w300` pour les listes et `original` seulement quand vous avez besoin d'une vue en taille réelle. ## Questions et réponses ### Comment lister tous les épisodes d'une série ? Lisez number_of_seasons dans la fiche de la série, puis appelez le point de terminaison de saison une fois par numéro de saison. Chaque réponse de saison contient son tableau episodes complet : une série de cinq saisons demande donc cinq requêtes. ### Que signifie le numéro de saison 0 ? La saison 0 contient les épisodes spéciaux, comme les coulisses et les résumés. Elle n'existe que si la série a des épisodes spéciaux, et une série sans eux renvoie 404 avec status_code 34 pour la saison 0. ### Pourquoi air_date est-il null pour certains épisodes ? L'épisode est annoncé mais n'a pas encore de date confirmée. Traitez null comme non programmé, et consultez next_episode_to_air dans la fiche de la série pour le prochain épisode daté. ### Puis-je obtenir un ordre DVD ou absolu des épisodes ? Pas sous forme de liste séparée. GET /3/tv/{series_id}/episode_groups nomme les ordres qu'a une série, mais amodb ne propose pas de point de terminaison qui renvoie les épisodes d'un groupe. Le point de terminaison de saison donne l'ordre standard. ## Pages liées - [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 des crédits](https://amodb.dev/fr/credits/): API crédits aux chemins et au JSON de TMDB v3. Distribution et équipe des films, séries, saisons et épisodes, avec les champs order, department et job. - [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 guide des épisodes](https://amodb.dev/fr/episode-guide-api/): API guide des épisodes avec les points de terminaison saisons et épisodes de TMDB v3 : noms, dates, durées, images et groupes d'épisodes, en 14 langues. - [Limites de débit](https://amodb.dev/fr/rate-limits/): amodb limite chaque clé en requêtes par minute sur une fenêtre glissante de 60 secondes : 20, 40 ou 120 selon l'offre. Lisez les en-têtes et gérez le 429. - [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/tv-seasons-episodes/