# API коллекций > Коллекция объединяет фильмы одной франшизы, например трилогию или многолетнюю киносерию. GET /3/collection/{collection_id} возвращает название, описание, изображения и массив parts с фильмами в порядке выхода. Фильмы ссылаются на свою коллекцию через belongs_to_collection, поэтому переходить можно в обе стороны: от фильма к франшизе и обратно. ## Эндпоинт `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Ответ: ```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" } ] } ``` ## Получение коллекции `GET /3/collection/{collection_id}` возвращает одну франшизу: название, описание, постер, фон (backdrop) и массив `parts`. Каждая часть содержит краткие сведения о фильме с полями, нужными для карточки, поэтому одного запроса хватает, чтобы отрисовать всю полку франшизы. В примере загружается коллекция 10 с фильмами Star Wars, а ее фильмы выводятся в порядке выхода. ```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) } } ``` ### Параметры | Параметр | Где | Обязателен | Описание | | --------------- | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | путь | да | Числовой ID коллекции, например `10`. | | `api_key` | строка запроса | один из двух | Ваш ключ. Используйте его или заголовок `Authorization: Bearer`. | | `language` | строка запроса | нет | Один из 14 поддерживаемых языков, например `en-US` или `fr-FR`. Задает язык названия и описания каждой части. По умолчанию `en-US`. | Собственные поля `name` и `overview` коллекции возвращаются как хранятся и не зависят от `language`. У некоторых коллекций они не на английском. ### Поля ответа | Поле | Тип | Примечания | | ---------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | | `id` | целое число | ID коллекции. | | `name` | строка | Название франшизы. | | `overview` | строка | Краткое описание. У некоторых коллекций пустое. | | `poster_path`, `backdrop_path` | строка или null | Добавьте к `https://img.amodb.dev/t/p/{size}`. См. [API изображений](https://amodb.dev/ru/images-api/). | | `parts` | массив | Краткие сведения о фильмах, сначала с самым ранним `release_date`. | | `parts[].id` | целое число | ID фильма. Передайте его в [сведения о фильме](https://amodb.dev/ru/movies/). | | `parts[].title`, `parts[].original_title` | строка | Локализованное и оригинальное название. | | `parts[].overview` | строка | Локализованное описание сюжета. | | `parts[].release_date` | строка | `YYYY-MM-DD` или пустая строка для фильма без даты. Такие части идут последними. | | `parts[].media_type` | строка | В коллекции всегда `movie`. | | `parts[].genre_ids` | массив | Числовые ID. Названия берите на странице [жанры](https://amodb.dev/ru/genres/). | | `parts[].adult`, `parts[].video` | логическое | `adult` всегда равно `false`, потому что фильмы для взрослых не отдаются. | | `parts[].original_language` | строка | Двухбуквенный код языка. | | `parts[].popularity` | число | Показатель популярности. | | `parts[].poster_path`, `parts[].backdrop_path` | строка или null | Изображения фильма. | | `parts[].vote_average`, `parts[].vote_count` | число, целое число | Сводная оценка пользователей. | ### Пример ответа Показаны две части из девяти. ```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" } ] } ``` Длинные строки на этой странице обрезаны до `...`. Реальный ответ содержит полный текст. ## Как найти коллекцию фильма С ID коллекции вы начинаете редко. Обычно вы исходите из фильма, а запись [сведения о фильме](https://amodb.dev/ru/movies/) подсказывает, к какой франшизе он относится. Поле `belongs_to_collection` содержит объект с полями `id`, `name`, `poster_path` и `backdrop_path`. Для фильма, который не входит во франшизу, например фильма 550, оно равно `null`. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` Пример ниже проходит по этой ссылке от фильма к его франшизе за два запроса. ```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); } ``` ## Изображения и поиск Постер и фон франшизы находятся в полях `poster_path` и `backdrop_path` записи коллекции. Соберите из них адрес файла так, как описано на странице [API изображений](https://amodb.dev/ru/images-api/). amodb не предоставляет пути `/collection/{collection_id}/images` и `/collection/{collection_id}/translations`, поэтому у коллекции нет списка альтернативных постеров и строк по языкам. Названия частей зависят от параметра `language`, а пути, которые возвращают строки по языкам, описаны на странице [переводы](https://amodb.dev/ru/translations/). Чтобы найти коллекцию по названию, используйте `GET /3/search/collection?query=matrix`, он описан на странице [поиск](https://amodb.dev/ru/search/). Каждый результат содержит поля `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` и `adult`. ## Ошибки | HTTP | status_code | Когда | | ---- | ----------- | ------------------------------------------------------------------------------------------------ | | 401 | 7 | Ключ отсутствует или неверен. | | 402 | 36 | Срок действия тарифа закончился. | | 404 | 34 | Коллекции с таким ID нет, или ID не является числом. | | 405 | 37 | Вы использовали метод записи на пути коллекции. | | 429 | 25 | Вы превысили лимит запросов в минуту. Подождите столько секунд, сколько указано в `Retry-After`. | Полный список смотрите на странице [ошибки](https://amodb.dev/ru/errors/), а лимиты тарифов на странице [лимиты запросов](https://amodb.dev/ru/rate-limits/). ## Практические замечания - Коллекции объединяют только фильмы. У фильма не больше одного объекта `belongs_to_collection`, поэтому один фильм соответствует одной франшизе. - Части приходят в порядке выхода. Фильмы с пустой датой идут последними, поэтому подпишите их как «дата пока не указана». - Запись коллекции кэшируется на edge-серверах на 6 часов, как и другие сведения, поэтому страница франшизы может использовать один ответ все это время. - Часть содержит только краткие поля. Длительность, актерский состав и рейтинги по каждому фильму запрашивайте через [сведения о фильме](https://amodb.dev/ru/movies/), когда пользователь его откроет. - В качестве ключа фильма используйте `parts[].id`, а не его позицию во франшизе. Порядок и даты со временем исправляются. - Перед показом проверьте, что `name` на вашем языке интерфейса. У некоторых коллекций название на другом языке, и `language` его не меняет. ## Вопросы и ответы ### Как узнать, входит ли фильм в коллекцию? Прочитайте belongs_to_collection в записи с данными о фильме. Это объект с полями id, name, poster_path и backdrop_path, а для отдельного фильма значение равно null. Подставьте этот id в путь коллекции. ### Приходят ли части в порядке выхода? Да. Массив parts отсортирован по release_date, самые старые фильмы идут первыми. У фильма без даты release_date пустой, и он стоит последним, поэтому подпишите его как «дата пока не указана». ### Есть ли коллекции у сериалов? Нет. Коллекции объединяют только фильмы. Сериал описывается сезонами и сериями, они описаны на страницах про сериалы и про сезоны и серии. ### Как найти коллекцию по названию? Используйте путь поиска коллекций, например /3/search/collection?query=matrix. Он возвращает постраничный список с полями id, name и изображениями. Возьмите id и вызовите эндпоинт коллекции, чтобы получить части. ## Связанные страницы - [API деталей фильма](https://amodb.dev/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках. - [API поиска](https://amodb.dev/ru/search/): API поиска с путями и JSON как в TMDB v3. Находите фильмы, сериалы, людей, коллекции, компании и ключевые слова по тексту, с фильтром по году и пагинацией. - [API изображений и хост изображений](https://amodb.dev/ru/images-api/): API изображений фильмов с путями TMDB v3: списки постеров, фонов, логотипов и кадров для каждого проекта, загрузка с img.amodb.dev в 10 размерах без ключа. - [API переводов](https://amodb.dev/ru/translations/): API переводов фильмов с путями TMDB v3: читайте все сохраненные названия, описания и слоганы фильма, сериала или серии сразу на всех языках. - [Discover API](https://amodb.dev/ru/discover/): Discover API с фильтрами TMDB v3. Фильмы и сериалы по жанру, актеру, студии, ключевому слову, году, рейтингу, длительности и провайдеру, с сортировкой. - [Быстрый старт](https://amodb.dev/ru/quickstart/): Первый вызов amodb: получите ключ, запросите детали фильма через curl, JavaScript, Python, PHP или Go и загрузите постер с img.amodb.dev. Меньше 2 минут. Обновлено: 2026-10-18. Source: https://amodb.dev/ru/collections/