# API de temporadas y episodios de TV > Lee una temporada con todos sus episodios en GET /3/tv/{series_id}/season/{season_number}, o un solo episodio un nivel más abajo. El JSON coincide con TMDB v3 con air_date, episode_number, runtime y still_path. Cada episodio trae crew y guest_stars, la temporada 0 reúne los especiales, y append_to_response añade credits, images y videos. ## Endpoint `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" ``` Respuesta: ```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 } ``` ## Obtén una temporada `GET /3/tv/{series_id}/season/{season_number}` devuelve una temporada y su array `episodes` completo en una sola respuesta. Los números de temporada empiezan en `1`, y `0` se reserva para los especiales. Toma el id de la serie y los números de temporada del registro de [series de TV](https://amodb.dev/es/tv-series/). El ejemplo lee la temporada 1 de Breaking Bad. El código imprime una línea por episodio. ```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) } } ``` ### Parámetros | Parámetro | En | Obligatorio | Descripción | | -------------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------------- | | `series_id` | ruta | sí | ID numérico de la serie de TV, por ejemplo `1396`. | | `season_number` | ruta | sí | Número entero de temporada. `0` devuelve los especiales. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | | `language` | consulta | no | Etiqueta TMDB como `en-US` o `fr-FR`. Se sirven 14 idiomas base. Por defecto `en-US`. | | `append_to_response` | consulta | no | Valores a nivel de temporada: `credits`, `external_ids`, `images`, `videos`. Los demás nombres se ignoran. | ### Campos de la respuesta | Campo | Tipo | Notas | | --------------------- | ------------ | ------------------------------------------------------------ | | `id`, `season_number` | entero | ID de la temporada y su número dentro de la serie. | | `name`, `overview` | texto | Texto localizado, vacío cuando no existe traducción. | | `air_date` | texto o null | Fecha del primer episodio, `YYYY-MM-DD`. | | `poster_path` | texto o null | Se añade a `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | número | Puntuación agregada de los usuarios para la temporada. | | `episodes` | array | Todos los episodios, con los campos de la sección siguiente. | ### Ejemplo de respuesta `GET /3/tv/1396/season/1?language=en-US`. La temporada tiene 7 episodios, así que `episodes` se recortó a una entrada, y los arrays `crew` y `guest_stars` de esa entrada se omitieron: ```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 } ``` Cada episodio de la respuesta de temporada también trae arrays `crew` y `guest_stars`, con la estructura de entrada descrita en [créditos](https://amodb.dev/es/credits/). `runtime` puede ser null en un episodio que aún no se ha emitido. ## Obtén un episodio `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` devuelve un episodio. La respuesta de temporada ya contiene todos los episodios con `crew` y `guest_stars`, así que usa este endpoint para actualizar un registro sin volver a cargar la temporada. Acepta `language` y `append_to_response` con `credits`, `external_ids`, `images`, `translations` y `videos`. Una solicitud como `/3/tv/1396/season/1/episode/1?append_to_response=credits` cuesta una sola solicitud. | Campo | Tipo | Notas | | --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | entero | ID del episodio. | | `show_id` | entero | ID de la serie. Aparece en la respuesta de temporada y en los punteros de la serie, no en la respuesta de un solo episodio. | | `season_number`, `episode_number` | entero | Posición dentro de la serie. Úsalos para construir la ruta de la solicitud. | | `name`, `overview` | texto | Texto localizado. | | `air_date` | texto o null | Solo fecha, sin hora ni zona horaria. Null cuando no está programado. | | `episode_type` | texto | `standard` para episodios normales. Para detectar un final, compara `episode_number` con el `episode_count` de esa temporada en el registro de la serie. | | `runtime` | entero o null | Minutos. | | `production_code` | texto | Código del estudio, a menudo vacío. | | `still_path` | texto o null | Fotograma del episodio. Usa `w300` u `original` de `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | número, entero | Puntuación agregada de los usuarios. | | `crew`, `guest_stars` | array | Créditos de este episodio, ver [créditos](https://amodb.dev/es/credits/). | ## Próximo y último episodio en el registro de la serie El endpoint de series devuelve `next_episode_to_air` y `last_episode_to_air`. Cada uno es un resumen de episodio con los campos de arriba, más `show_id` y sin `crew` ni `guest_stars`. El próximo es null en las series terminadas y en las series en curso sin fecha confirmada. El ejemplo lee South Park, una serie en curso. ```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'); ``` Para una cuenta atrás, compara `air_date` con la fecha local del espectador. El valor no lleva hora del día, así que muestra una fecha y no una hora. ## Subrecursos de temporada y episodio Las rutas de temporada y episodio tienen sus propios subrecursos. Varios de ellos devuelven hoy datos vacíos. | Método y ruta | Devuelve | | --------------------------------------------------------- | --------------------------------------------------------------- | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` y `crew` de la temporada | | `GET /tv/{series_id}/season/{season_number}/images` | `id` y un array `posters` vacío | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` y un array `results` vacío | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` más `tvdb_id`, `wikidata_id` y otros ids, todos null | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` y un array `translations` vacío | | `GET .../episode/{episode_number}/credits` | `id`, un `cast` vacío, `crew` y `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` y un array `stills` con el fotograma del episodio | | `GET .../episode/{episode_number}/videos` | `id` y un array `results` vacío | | `GET .../episode/{episode_number}/external_ids` | `id` más `imdb_id`, `tvdb_id` y otros ids, todos null | | `GET .../episode/{episode_number}/translations` | `id` y un array `translations` con nombre y sinopsis por idioma | Los créditos de temporada y episodio se explican en [créditos](https://amodb.dev/es/credits/), y los fotogramas en [imágenes](https://amodb.dev/es/images-api/). amodb no ofrece las rutas `changes` de TMDB ni un endpoint para los episodios de un grupo de episodios. ## Errores | HTTP | status_code | Cuándo | | ---- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Falta la clave o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 404 | 34 | La serie, la temporada o el episodio no existe, por ejemplo la temporada `0` en una serie sin especiales, o la ruta no se ofrece. | | 405 | 37 | Llamaste a un método de escritura. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos indicados en `Retry-After`. | Consulta [errores](https://amodb.dev/es/errors/) para ver el formato completo del cuerpo y [límites de solicitudes](https://amodb.dev/es/rate-limits/) para las ventanas. ## Notas prácticas - Las temporadas y los episodios se guardan en caché 6 horas. Vuelve a leer la temporada actual una o dos veces al día mientras se emite la serie. - Una serie de 10 temporadas necesita 10 llamadas de temporada. En el plan de 20 solicitudes por minuto eso usa la mitad del cupo de un minuto, y una repetición dentro de las 6 horas se responde desde la caché perimetral. - Un episodio sin emitir puede tener `air_date` null, `runtime` null y `overview` vacío. Muestra un marcador de posición en lugar de fallar. - Los fotogramas son tomas panorámicas, no pósteres. Pide `w300` en las listas y `original` solo cuando necesites una vista a tamaño completo. ## Preguntas y respuestas ### ¿Cómo listo todos los episodios de una serie? Lee number_of_seasons del registro de la serie y llama al endpoint de temporada una vez por cada número de temporada. Cada respuesta de temporada trae su array episodes completo, así que una serie de cinco temporadas necesita cinco solicitudes. ### ¿Qué significa el número de temporada 0? La temporada 0 reúne los especiales, como piezas del detrás de cámaras y resúmenes. Solo existe cuando la serie tiene especiales, y una serie sin ellos devuelve 404 con status_code 34 para la temporada 0. ### ¿Por qué air_date es null en algunos episodios? El episodio está anunciado pero todavía no tiene una fecha confirmada. Trata null como sin programar, y revisa next_episode_to_air en el registro de la serie para ver el siguiente episodio con fecha. ### ¿Puedo obtener el orden de DVD o el orden absoluto de episodios? No como un listado aparte. GET /3/tv/{series_id}/episode_groups indica los órdenes que tiene una serie, pero amodb no ofrece un endpoint que devuelva los episodios de un grupo. El endpoint de temporada da el orden estándar. ## Páginas relacionadas - [API de series de TV](https://amodb.dev/es/tv-series/): API de series de TV con las mismas rutas y JSON que TMDB v3. Obtén una serie con temporadas, cadenas y próximo episodio, más clasificaciones y plataformas. - [API de créditos](https://amodb.dev/es/credits/): API de créditos con las mismas rutas y el mismo JSON que TMDB v3. Obtén reparto y equipo técnico de películas, series, temporadas y episodios con order y job. - [API de imágenes y host de imágenes](https://amodb.dev/es/images-api/): API de imágenes de películas con rutas TMDB v3: lista pósters, fondos, logos y fotogramas por título y cárgalos desde img.amodb.dev en 10 tamaños sin clave. - [API de guía de episodios](https://amodb.dev/es/episode-guide-api/): API de guía de episodios con los endpoints de temporada y episodio de TMDB v3: nombres, fechas, duraciones, imágenes y grupos de episodios, en 14 idiomas. - [Límites de solicitudes](https://amodb.dev/es/rate-limits/): amodb limita cada clave por solicitudes por minuto en una ventana deslizante de 60 segundos: 20, 40 o 120 según el plan. Lee los encabezados y gestiona el 429. - [Inicio rápido](https://amodb.dev/es/quickstart/): Haz tu primera llamada a amodb: consigue una clave, pide los detalles de una película en curl, JavaScript, Python, PHP o Go y carga el póster. En 2 minutos. Actualizado: 2026-10-18. Source: https://amodb.dev/es/tv-seasons-episodes/