# API de colecciones > Una colección agrupa las películas de una misma saga, como una trilogía o una serie larga de películas. GET /3/collection/{collection_id} devuelve su nombre, sinopsis, imágenes y un array parts con las películas en orden de estreno. Cada película apunta a su colección con belongs_to_collection, así que puedes ir en ambos sentidos. ## Endpoint `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Respuesta: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## Obtener una colección `GET /3/collection/{collection_id}` devuelve una saga: su nombre, una sinopsis, un póster, una imagen de fondo (backdrop) y el array `parts`. Cada parte es un resumen de película con los campos que necesitas para una tarjeta, así que una sola llamada puede dibujar una fila completa de la saga. El ejemplo carga la colección 10, las películas de Star Wars, e imprime sus películas en orden de estreno. ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?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 collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```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"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?language=en-US" req, _ := http.NewRequest("GET", url, 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 c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### Parámetros | Parámetro | En | Obligatorio | Descripción | | --------------- | -------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | ruta | sí | Id numérico de la colección, por ejemplo `10`. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | | `language` | consulta | no | Uno de los 14 idiomas servidos, por ejemplo `en-US` o `fr-FR`. Define el idioma del título y la sinopsis de cada parte. Valor por defecto `en-US`. | El `name` y el `overview` de la propia colección llegan tal como están guardados y no cambian con `language`. En algunas colecciones no están en inglés. ### Campos de la respuesta | Campo | Tipo | Notas | | ---------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | | `id` | entero | Id de la colección. | | `name` | texto | Nombre de la saga. | | `overview` | texto | Descripción breve. Vacía en algunas colecciones. | | `poster_path`, `backdrop_path` | texto o null | Añádelo a `https://img.amodb.dev/t/p/{size}`. Consulta [imágenes](https://amodb.dev/es/images-api/). | | `parts` | array | Resúmenes de películas, con la `release_date` más antigua primero. | | `parts[].id` | entero | Id de la película. Pásalo a los [detalles de película](https://amodb.dev/es/movies/). | | `parts[].title`, `parts[].original_title` | texto | Título localizado y título original. | | `parts[].overview` | texto | Sinopsis localizada. | | `parts[].release_date` | texto | `YYYY-MM-DD`, o una cadena vacía para una película sin fecha. Esas partes van al final. | | `parts[].media_type` | texto | Siempre `movie` dentro de una colección. | | `parts[].genre_ids` | array | Ids numéricos. Los nombres salen de [géneros](https://amodb.dev/es/genres/). | | `parts[].adult`, `parts[].video` | booleano | `adult` es siempre `false`, porque no se sirven títulos para adultos. | | `parts[].original_language` | texto | Código de idioma de dos letras. | | `parts[].popularity` | número | Puntuación de popularidad. | | `parts[].poster_path`, `parts[].backdrop_path` | texto o null | Imágenes de la película. | | `parts[].vote_average`, `parts[].vote_count` | número, entero | Puntuación agregada de los usuarios. | ### Ejemplo de respuesta Se muestran dos de las nueve partes. ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` Las cadenas largas se cortan con `...` en esta página. La respuesta real contiene el texto completo. ## Encontrar la colección de una película Pocas veces empiezas desde un id de colección. Empiezas desde una película, y el registro de [detalles de película](https://amodb.dev/es/movies/) te dice a cuál pertenece. El campo `belongs_to_collection` es un objeto con `id`, `name`, `poster_path` y `backdrop_path`. Es `null` cuando la película no forma parte de una saga, como la película 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` El siguiente ejemplo sigue ese vínculo desde una película hasta su saga en dos solicitudes. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## Imágenes y búsqueda El póster y la imagen de fondo de una saga son los campos `poster_path` y `backdrop_path` del registro de la colección. Construye la dirección del archivo a partir de ellos, como se describe en [imágenes](https://amodb.dev/es/images-api/). amodb no ofrece las rutas `/collection/{collection_id}/images` y `/collection/{collection_id}/translations`, así que una colección no tiene una lista de pósters alternativos ni filas por idioma. Los títulos de las partes siguen el parámetro `language`, y [traducciones](https://amodb.dev/es/translations/) cubre las rutas que sí devuelven filas por idioma. Para encontrar una colección por nombre, usa `GET /3/search/collection?query=matrix`, descrita en [búsqueda](https://amodb.dev/es/search/). Cada resultado tiene `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` y `adult`. ## Errores | HTTP | status_code | Cuándo | | ---- | ----------- | --------------------------------------------------------------------------- | | 401 | 7 | La clave falta o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 404 | 34 | No hay ninguna colección con ese id, o el id no es un número. | | 405 | 37 | Usaste un método de escritura en una ruta de colección. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos de `Retry-After`. | Consulta [errores](https://amodb.dev/es/errors/) para ver la lista completa y [límites de solicitudes](https://amodb.dev/es/rate-limits/) para los límites de cada plan. ## Notas prácticas - Las colecciones agrupan solo películas. Una película tiene como máximo un objeto `belongs_to_collection`, así que cada película corresponde a una sola saga. - Las partes llegan en orden de estreno. Las películas con fecha vacía van al final, así que márcalas como sin fecha todavía. - El registro de la colección se guarda en la caché perimetral 6 horas, como el resto de los detalles, así que una página de saga puede reutilizar una respuesta durante ese tiempo. - Una parte trae solo campos de resumen. Pide la duración, los créditos y las puntuaciones de cada película en los [detalles de película](https://amodb.dev/es/movies/) cuando el usuario la abra. - Usa `parts[].id` como clave de una película, no su posición en la saga. Los órdenes y las fechas se corrigen con el tiempo. - Comprueba que `name` esté en tu idioma de visualización antes de mostrarlo. Algunas colecciones traen el nombre en otro idioma, y `language` no lo cambia. ## Preguntas y respuestas ### ¿Cómo sé si una película pertenece a una colección? Lee belongs_to_collection en el registro de detalles de la película. Es un objeto con id, name, poster_path y backdrop_path, o null cuando la película va sola. Usa ese id en la ruta de la colección. ### ¿Las partes llegan en orden de estreno? Sí. El array parts viene ordenado de la más antigua a la más reciente según release_date. Una película sin fecha tiene release_date vacío y va al final, así que márcala como sin fecha todavía. ### ¿Las series de TV tienen colecciones? No. Las colecciones agrupan películas. Una serie se describe con sus temporadas y episodios, que se documentan en las páginas de series de TV y de temporadas y episodios. ### ¿Cómo busco una colección por nombre? Usa la ruta de búsqueda de colecciones, por ejemplo /3/search/collection?query=matrix. Devuelve una lista paginada con id, name e imágenes. Toma el id y llama al endpoint de la colección para obtener las partes. ## Páginas relacionadas - [API de detalles de película](https://amodb.dev/es/movies/): API de detalles de película con rutas y JSON de TMDB v3. Obtén una película por id y añade créditos, puntuaciones y moods con append_to_response, en 14 idiomas. - [API de búsqueda](https://amodb.dev/es/search/): API de búsqueda con rutas y JSON de TMDB v3. Encuentra películas, series, personas, colecciones, productoras y palabras clave por texto, con filtros de año. - [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 traducciones](https://amodb.dev/es/translations/): API de traducciones de películas con rutas TMDB v3: lee todos los títulos, sinopsis y eslóganes de una película, serie o episodio en todos sus idiomas. - [API Discover](https://amodb.dev/es/discover/): API Discover con los mismos filtros que TMDB v3. Lista películas y series por género, reparto, productora, palabra clave, año, nota, duración y plataforma. - [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/collections/