# API de series de TV > El endpoint de series de TV devuelve una serie por id en GET /3/tv/{series_id}: nombres, sinopsis, estado, temporadas, cadenas, géneros y punteros al último y al próximo episodio. El JSON coincide con TMDB v3, así que los clientes existentes solo necesitan una nueva URL base. Añade append_to_response para incorporar clasificaciones por edad, créditos y puntuaciones en una sola solicitud. ## Endpoint `GET /3/tv/{series_id}` ```bash curl "https://api.amodb.dev/3/tv/1396?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Respuesta: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" }, { "id": 33742, "logo_path": "/2jdh2sEa0R6y6uT0F7g0IgA2WO8.png", "name": "High Bridge Productions", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "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.", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 }, { "air_date": "2009-03-08", "episode_count": 13, "id": 3573, "name": "第 2 季", "overview": "贩卖冰毒的沃尔特老师在毒品交易中越陷越深，这引起了竞争对手的注意并使他在缉毒局的小舅子陷入危险中。", "poster_path": "/zMO024gJxKhTJfWqM0XTYd3SgKj.jpg", "season_number": 2, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 8.955, "vote_count": 18873 } ``` ## Obtén los detalles de una serie de TV `GET /3/tv/{series_id}` devuelve el registro principal de una serie: nombres, sinopsis, estado, géneros, cadenas, la lista de temporadas y punteros al último y al próximo episodio. El id es el id numérico de TV de TMDB, así que una serie que guardas como `1396` conserva ese id aquí. Los ids de películas y de TV son espacios separados, así que guarda siempre el tipo de medio junto al número. El ejemplo pide Breaking Bad en inglés y añade sus clasificaciones por edad y puntuaciones externas en la misma llamada. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' }); const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const show = await res.json(); const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US'); console.log(show.name, show.status, show.number_of_seasons, us?.rating); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396", params={"language": "en-US", "append_to_response": "content_ratings,ratings"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() show = r.json() us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None) print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"]) ``` ```php 'en-US', 'append_to_response' => 'content_ratings,ratings', ]); $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"); } $show = json_decode($body, true); echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type Show struct { Name string `json:"name"` Status string `json:"status"` NumberOfSeasons int `json:"number_of_seasons"` NumberOfEpisodes int `json:"number_of_episodes"` Next *struct { AirDate string `json:"air_date"` } `json:"next_episode_to_air"` } func main() { q := url.Values{"language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), 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 Show if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } next := "none scheduled" if s.Next != nil { next = s.Next.AirDate } fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next) } ``` ### Parámetros | Parámetro | En | Obligatorio | Descripción | | -------------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------- | | `series_id` | ruta | sí | ID numérico de TV, por ejemplo `1396`. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | | `language` | consulta | no | Etiqueta TMDB como `en-US`, `uk-UA` o `es-ES`. Se sirven 14 idiomas base. Por defecto `en-US`. | | `append_to_response` | consulta | no | Lista separada por comas de subrecursos que se incorporan a la respuesta, hasta 20 valores. | ### Campos de la respuesta | Campo | Tipo | Notas | | -------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `id` | entero | ID de TV. | | `name`, `original_name` | texto | Título localizado y original. Los nombres originales en japonés o coreano se quedan en `original_name`. | | `overview`, `tagline` | texto | Texto localizado, vacío cuando no existe traducción. | | `first_air_date`, `last_air_date` | texto o null | `YYYY-MM-DD`. | | `status` | texto | Ciclo de vida, ver la tabla siguiente. | | `in_production` | booleano | `true` mientras la serie sigue en producción. | | `number_of_seasons`, `number_of_episodes` | entero | Totales, tal como están guardados para la serie. | | `episode_run_time` | array | Duraciones típicas de episodio en minutos, puede estar vacío. | | `seasons` | array | Un resumen por temporada con `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`. | | `last_episode_to_air`, `next_episode_to_air` | objeto o null | Resúmenes de episodio, con la forma de los objetos de [temporadas y episodios](https://amodb.dev/es/tv-seasons-episodes/). | | `networks`, `production_companies` | array | `id`, `name`, `logo_path`, `origin_country`. | | `production_countries`, `spoken_languages` | array | Países con `iso_3166_1` y `name`. Idiomas con `english_name`, `iso_639_1` y `name`. | | `created_by` | array | Creadores con `id`, `name`, `profile_path` y `credit_id`. Vacío en la mayoría de las series. | | `genres` | array | Objetos con `id` y `name`. Los ids de género de TV son distintos de los de películas. | | `origin_country`, `original_language`, `languages` | array, texto | Códigos de país y de idioma. | | `homepage` | texto | Sitio oficial, vacío cuando no se conoce. | | `poster_path`, `backdrop_path` | texto o null | Se añaden a `https://img.amodb.dev/t/p/{size}`. Ver [imágenes](https://amodb.dev/es/images-api/). | | `popularity` | número | Puntuación relativa que usa la lista de populares. | | `vote_average`, `vote_count` | número, entero | Puntuación agregada de los usuarios. | | `adult` | booleano | Siempre `false`. Los títulos para adultos nunca se sirven. | ### Ejemplo de respuesta `GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings`, con arrays y textos largos acortados: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 9, "vote_count": 18863, "content_ratings": { "results": [ { "descriptors": [], "iso_3166_1": "AT", "rating": "16" }, { "descriptors": [], "iso_3166_1": "AU", "rating": "MA 15+" } ] }, "ratings": { "imdb": { "value": 9.5, "votes": 2671962 }, "kinopoisk": { "value": 8.9, "votes": null }, "metacritic": null, "rotten_tomatoes": { "value": 96, "votes": null }, "tmdb": { "value": 9, "votes": 18863 } } } ``` Los bloques `content_ratings` y `ratings` vienen de `append_to_response`. Los nombres y las sinopsis dentro de `seasons`, `last_episode_to_air` y `next_episode_to_air` se guardan por registro y pueden no seguir `language`, como muestra el nombre de episodio en hebreo de arriba. Lee el texto localizado de temporadas y episodios desde el [endpoint de temporada](https://amodb.dev/es/tv-seasons-episodes/). ## Estado y punteros de episodio `status` te dice en qué punto de su vida está una serie, y `next_episode_to_air` te dice cuándo volver a mirar. | Valor de `status` | Significado | `next_episode_to_air` | | -------------------------- | ----------------------------------- | --------------------------------------------------- | | `Returning Series` | En emisión o entre temporadas. | Definido cuando se conoce una fecha, si no es null. | | `Planned`, `In Production` | Todavía no es una serie regular. | Normalmente null. | | `Ended` | Terminó su emisión. | Null. | | `Canceled` | Se detuvo antes del final previsto. | Null. | Una serie en curso entre temporadas tiene un `next_episode_to_air` null, así que interpreta null como «fecha desconocida» y no como «terminada». El array `seasons` lista un resumen por temporada, y la temporada `0` reúne los especiales. Para leer los episodios de una temporada, llama al endpoint descrito en [temporadas y episodios](https://amodb.dev/es/tv-seasons-episodes/). ## Endpoints relacionados de series Todas las rutas comparten la base `https://api.amodb.dev/3`, y los endpoints con texto localizado también aceptan `language`. | Método y ruta | Devuelve | Parámetros adicionales | | ---------------------------------------- | ---------------------------------------------------------------------- | ---------------------- | | `GET /tv/{series_id}/alternative_titles` | `{id, results}` con `iso_3166_1`, `title`, `type`, a menudo vacío | ninguno | | `GET /tv/{series_id}/content_ratings` | Clasificación por edad por país | ninguno | | `GET /tv/{series_id}/episode_groups` | Lista de órdenes alternativos de episodios, como DVD o arco argumental | ninguno | | `GET /tv/{series_id}/recommendations` | Una lista de 20 series recomendadas | ninguno | | `GET /tv/{series_id}/similar` | Una lista de 20 series similares | ninguno | | `GET /tv/{series_id}/reviews` | `results` está vacío en la mayoría de las series | ninguno | | `GET /tv/{series_id}/lists` | Listas públicas que contienen la serie | `page` | | `GET /tv/{series_id}/watch/providers` | Proveedores de streaming, alquiler y compra por país | ninguno | | `GET /tv/latest` | El registro de serie más reciente añadido | ninguno | Las listas de recomendaciones y de similares siempre devuelven la página 1 con 20 elementos. La respuesta de `lists` está paginada con `page`, 20 listas por página. Las demás listas paginadas de la API aceptan `page` de 1 a 500. Las clasificaciones por edad llegan como entradas de `results` con `iso_3166_1`, `rating` y `descriptors`, así que elige la entrada que coincide con el país del espectador. Los proveedores de visionado se organizan por código de país, y cada país contiene un `link` más listas `flatrate`, `rent` y `buy` con `provider_id`, `provider_name`, `logo_path` y `display_priority`. Los ids de proveedor para filtrar salen de las listas de consulta de [géneros y listas de consulta](https://amodb.dev/es/genres/). La lista de grupos de episodios devuelve `id` (un texto), `name`, `description`, `type`, `episode_count`, `group_count` y `network`. amodb lista los grupos, pero no ofrece un endpoint que devuelva los episodios de un grupo. Tampoco ofrece las rutas `changes` de TMDB. ## Combina más datos en una sola llamada Lista los subrecursos en `append_to_response` y cada uno llega bajo su propia clave. Toda la llamada cuenta una sola vez contra tus 20, 40 o 120 solicitudes por minuto. Funcionan hasta 20 valores, y los nombres desconocidos se ignoran sin error. Estos valores funcionan en una serie: | Valor | Añade | Detalles | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credits` | Reparto y equipo técnico | [Créditos](https://amodb.dev/es/credits/) | | `external_ids` | Ids como `imdb_id`, `tvdb_id` y `wikidata_id` | [Buscar por ID externo](https://amodb.dev/es/find-by-external-id/) | | `images`, `videos` | Pósters, imágenes de fondo (backdrop) y tráilers | [Imágenes](https://amodb.dev/es/images-api/), [Vídeos](https://amodb.dev/es/videos-trailers/) | | `keywords`, `translations` | Etiquetas y textos traducidos | [Palabras clave](https://amodb.dev/es/keywords/), [Traducciones](https://amodb.dev/es/translations/) | | `content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews` | Los subrecursos de la tabla anterior | Esta página | | `ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes` | Extras de amodb | [Puntuaciones](https://amodb.dev/es/ratings/), [Moods](https://amodb.dev/es/moods/), [Bandas sonoras](https://amodb.dev/es/soundtracks/), [Horarios de cine](https://amodb.dev/es/showtimes/) | ## Errores Una llamada fallida devuelve el cuerpo de error de TMDB. Un id incorrecto da `status_code` 34 con el mensaje «The resource you requested could not be found.» | HTTP | status_code | Cuándo | | ---- | ----------- | ------------------------------------------------------------------------------------- | | 401 | 7 | Falta la clave o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 404 | 34 | No hay ninguna serie con ese id, es un título para adultos, o la ruta no se ofrece. | | 405 | 37 | Llamaste a un método de escritura, como puntuar una serie. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos indicados en `Retry-After`. | La lista completa está en [errores](https://amodb.dev/es/errors/), y los límites por plan están en [límites de solicitudes](https://amodb.dev/es/rate-limits/). ## Notas prácticas - Los detalles de la serie y todos los subrecursos anteriores se guardan en caché 6 horas. Consulta `last_episode_to_air` como máximo unas pocas veces al día. - Solicita el idioma que muestras. Un `overview` vacío significa que no existe traducción, así que vuelve a solicitar con `en-US` como respaldo. - Usa `number_of_seasons` como límite del bucle cuando obtengas todas las temporadas, una llamada por cada una. - Para listar series en lugar de leer una, consulta [búsqueda](https://amodb.dev/es/search/), [discover](https://amodb.dev/es/discover/) y [tendencias y listas](https://amodb.dev/es/trending-lists/). ## Preguntas y respuestas ### ¿Cómo sé si una serie sigue en emisión? Lee status junto con next_episode_to_air. Una serie en curso con un next_episode_to_air que no es null tiene un episodio programado. Las series terminadas y canceladas siempre devuelven null ahí, y una serie entre temporadas también puede hacerlo. ### ¿El registro de la serie incluye un id de IMDb? No en el registro base, igual que en TMDB. Añade append_to_response=external_ids para obtener imdb_id y tvdb_id, o llama al endpoint find con un id de IMDb para pasar de un id externo al id de la serie. ### ¿Puedo obtener las puntuaciones de IMDb y Rotten Tomatoes de una serie? Sí. Llama a GET /3/tv/{series_id}/ratings o añade append_to_response=ratings. Obtienes las puntuaciones de IMDb, Kinopoisk, Metacritic, Rotten Tomatoes y TMDB, cada una con value y votes, o null cuando la puntuación no se conoce. ### ¿Cuánto tiempo se guardan en caché los datos de TV? Los detalles de la serie y sus subrecursos se guardan en la caché perimetral 6 horas, así que un episodio recién emitido puede tardar ese tiempo en aparecer en last_episode_to_air. Las listas como las de series en emisión se guardan 30 minutos. ## Páginas relacionadas - [API de temporadas y episodios de TV](https://amodb.dev/es/tv-seasons-episodes/): API de temporadas y episodios de TV con las mismas rutas y JSON que TMDB v3. Lee una temporada con todos sus episodios, o un episodio con fecha y duración. - [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. - [Puntuaciones de películas y series](https://amodb.dev/es/ratings/): API de puntuaciones de películas: IMDb, Kinopoisk, Metacritic, Rotten Tomatoes y TMDB de un título en una sola llamada, con null si falta una fuente. - [API de series de TV para temporadas y episodios](https://amodb.dev/es/tv-show-api/): API de series de TV con estado, cadenas, temporadas, episodios y next_episode_to_air. JSON de TMDB v3 en 14 idiomas, desde 20 solicitudes por minuto. - [Errores](https://amodb.dev/es/errors/): Cada error de amodb con su estado HTTP, su status_code de TMDB y su mensaje, más la forma de error de OMDb. Qué significa cada uno y qué debe hacer tu cliente. - [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-series/