# API довідника серій > API довідника серій повертає всі серії серіалу через GET /3/tv/{tv_id}/season/{season_number}. Кожна серія має назву, опис, дату виходу, тривалість і кадр. Список episode_groups називає альтернативні порядки, як-от DVD чи наскрізний. Шляхи й JSON збігаються з TMDB v3, тож наявним клієнтам потрібен лише новий базовий URL. ## Отримайте всі серії сезону `GET /3/tv/{tv_id}/season/{season_number}` повертає сезон із повним масивом `episodes`. Кожна серія має `episode_number`, `name`, `overview`, `air_date`, `runtime` і `still_path`. Id це числові id, які використовує TMDB, наприклад `1396` для Breaking Bad. Ви отримуєте сезони, серії з датами й тривалістю, кадри, наступну та останню серії серіалу в ефірі, а також список альтернативних порядків серій. Текстові поля залежать від параметра `language`, а опис лишається порожнім, якщо перекладу немає. ## Які дані ви отримуєте | Ендпоінт | Що повертає | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `GET /3/tv/{tv_id}` | Підсумок `seasons`, `number_of_seasons`, `status`, `next_episode_to_air`, `last_episode_to_air` | | `GET /3/tv/{tv_id}/season/{season_number}` | Один сезон з усіма його `episodes` | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}` | Одна серія з `crew` і `guest_stars` | | `GET /3/tv/{tv_id}/episode_groups` | Назва, `type` і кількість серій кожного альтернативного порядку, визначеного для серіалу | Поля серії: | Поле | Тип | Примітки | | --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- | | `id`, `show_id` | ціле число | Id серії та id серіалу. `show_id` є у списках сезону та в `next_episode_to_air`, але не на шляху однієї серії | | `episode_number`, `season_number` | ціле число | Позиція в сезоні | | `episode_type` | рядок | Наприклад, `standard` | | `name`, `overview` | рядок | Локалізуються через `language` | | `air_date` | рядок або null | `YYYY-MM-DD`, порожнє або null, якщо не анонсовано | | `runtime` | ціле число або null | Хвилини | | `still_path` | рядок або null | Додається до `https://img.amodb.dev/t/p/{size}` | | `vote_average`, `vote_count` | число, ціле число | Наразі `0` для серій | | `production_code` | рядок | Код студії, часто порожній | | `crew`, `guest_stars` | масив | Люди, вказані в титрах серії, з тими самими полями, що й учасник акторського складу | ## Почніть за 3 кроки 1. Оберіть тариф на сторінці [ціни](https://amodb.dev/uk/pricing/). Усі тарифи повертають однакові дані про серії, відрізняється лише кількість запитів. 2. Створіть ключ у кабінеті акаунта й збережіть його в змінній середовища. 3. Надішліть запит до `/3/tv/{tv_id}/season/1` з ключем у заголовку Bearer або як `api_key`. ## Приклад запиту Приклад отримує сезон 1 серіалу Breaking Bad (id серіалу `1396`) англійською. Програма на Go розбирає його в типізовані структури й виводить по одному рядку на серію з датою виходу, тривалістю та URL кадру. ```bash curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Episode struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` StillPath *string `json:"still_path"` } type Season struct { Name string `json:"name"` SeasonNumber int `json:"season_number"` Episodes []Episode `json:"episodes"` } func main() { client := &http.Client{Timeout: 10 * time.Second} url := "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" req, err := http.NewRequest("GET", url, nil) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(fmt.Sprintf("amodb returned %s", res.Status)) } var season Season if err := json.NewDecoder(res.Body).Decode(&season); err != nil { panic(err) } fmt.Println(season.Name) for _, e := range season.Episodes { still := "no still" if e.StillPath != nil { still = "https://img.amodb.dev/t/p/w300" + *e.StillPath } fmt.Printf("S%02dE%02d %s %3d min %s %s\n", season.SeasonNumber, e.EpisodeNumber, e.AirDate, e.Runtime, e.Name, still) } } ``` Скорочена відповідь: 2 із 7 серій, у кожної по одному члену знімальної групи та одній запрошеній зірці. ```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...", "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" } ], "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" } ] }, { "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 mor...", "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" } ], "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" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Отримайте весь серіал amodb не приймає значення на кшталт `season/1` в `append_to_response`, тож запити сезонів лишаються окремими. Спершу прочитайте `number_of_seasons` і список `seasons` з деталей серіалу, а потім запитайте кожен сезон у циклі. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path) { const res = await fetch(base + path, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const show = await get('/tv/1396'); for (const { season_number } of show.seasons) { const season = await get(`/tv/1396/season/${season_number}`); console.log(season.name, season.episodes.length); } ``` `seasons` містить сезон 0, коли в серіалу є спеціальні випуски, тож Breaking Bad коштує 1 запит деталей плюс 6 запитів сезонів. Серіал із 10 сезонами коштує 11 запитів. Деталі кешуються на периферії на 6 годин, тож зберігайте результат і оновлюйте його за розкладом. ## Дати виходу та що далі `GET /3/tv/{tv_id}` містить `next_episode_to_air` і `last_episode_to_air`, повні об'єкти серій з `name`, `air_date`, `season_number`, `episode_number`, `runtime` і `still_path`. `next_episode_to_air` дорівнює `null`, коли нічого не анонсовано. Поєднайте його зі `status` (наприклад, `Returning Series`, `Ended` або `Canceled`), щоб вирішити, чи показувати зворотний відлік. `air_date` це календарна дата без часу доби. Порівнюйте її з сьогоднішньою датою, щоб позначати нові серії. Для розкладу того, що йде в ефірі, списки `airing_today` і `on_the_air` на сторінці [списки трендів](https://amodb.dev/uk/trending-lists/) кешуються на 30 хвилин. ## Кадри й тривалість Використовуйте `w185` або `w300` для рядків списку й `original` для повного розміру. Розміри кадрів: `w92`, `w185`, `w300` і `original`. У серії може не бути кадру, тож показуйте заглушку, коли `still_path` дорівнює `null`. Хост зображень не потребує ключа, дивіться [API зображень](https://amodb.dev/uk/images-api/). `runtime` вимірюється в хвилинах і може бути `null`. Щоб показати час марафону для сезону, додайте `runtime` по всіх `episodes` і рахуйте `null` як 0. Додайте `append_to_response=credits,images` до шляху однієї серії, щоб отримати об'єкт `credits` і список `stills`. Масив `cast` серії порожній, а люди містяться в `crew` і `guest_stars`. Деталі на сторінках [сезони та серії](https://amodb.dev/uk/tv-seasons-episodes/) і [акторський склад і знімальна група](https://amodb.dev/uk/credits/). ## Альтернативні порядки з групами серій Деякі серіали дивляться в іншому порядку, ніж вони виходили в ефір. `GET /3/tv/{tv_id}/episode_groups` перелічує порядки, визначені для серіалу. Кожен запис має `id`, `name`, `description`, `type`, `episode_count`, `group_count` і `network`. Масив `results` порожній, якщо жодного не визначено. | `type` | Порядок | | ------ | ----------------------- | | 1 | Оригінальна дата виходу | | 2 | Наскрізний | | 3 | DVD | | 4 | Цифровий | | 5 | Сюжетна арка | | 6 | Виробничий | | 7 | ТБ | amodb повертає лише цей список. Він не надає `GET /3/tv/episode_group/{id}`, тож серії всередині групи недоступні. Для даних про серії використовуйте ендпоінти сезонів. ## Порівняння | Можливість | Скрапінг сторінок серій | Безкоштовний API метаданих | amodb | | ------------------ | ----------------------------------- | -------------------------- | ------------------------------------------------- | | Повний сезон | Одне завантаження сторінки на сезон | Дивіться їхню документацію | Один запит, масив `episodes` уже включено | | Весь серіал | Обхід кожного сезону | Дивіться їхню документацію | Один запит на сезон, перелічені в `seasons` | | Дати виходу | Розбір тексту | Дивіться їхню документацію | `air_date` та `next_episode_to_air` | | Кадри | Завантажувати й змінювати розмір | Дивіться їхню документацію | Фіксовані розміри на `img.amodb.dev`, без ключа | | Інші порядки серій | Недоступно | Дивіться їхню документацію | Список `episode_groups`, вміст груп не віддається | | Мови | Одна локаль на сайт | Дивіться їхню документацію | 14 мов через `language` | ## Ціни Тарифи передплачуються на 1, 3, 6, 12 або 24 місяці, за довші періоди діє знижка 0, 10, 20, 30 або 40 відсотків, і вони ніколи не поновлюються самі. Тарифи з 20, 40 і 120 запитами на хвилину повертають усі ендпоінти з цієї сторінки. Оновлення серіалу коштує один запит на деталі й по одному на сезон. Безкоштовного тарифу немає. Оберіть тариф на сторінці [ціни](https://amodb.dev/uk/pricing/). ## Запитання й відповіді ### Як отримати список усіх серій серіалу? Прочитайте number_of_seasons з GET /3/tv/{tv_id}, потім викличте GET /3/tv/{tv_id}/season/{season_number} для кожного сезону. Кожна відповідь сезону містить повний масив episodes, тож окремий запит на кожну серію не потрібен. Деякі сезони повертаються з порожнім масивом episodes, якщо даних про серії немає. ### Чи можна отримати кілька сезонів одним запитом? Ні. amodb ігнорує значення на кшталт season/1 в append_to_response, тож кожен сезон це окремий запит. Серіал із 10 сезонами коштує 11 запитів: один на деталі й по одному на сезон. ### Що таке група серій? Група серій це альтернативний порядок тих самих серій, наприклад DVD, наскрізний або за сюжетними арками. GET /3/tv/{tv_id}/episode_groups перелічує їх із назвою, типом і кількістю серій. Самі серії всередині групи amodb не віддає. ### Як дізнатися, коли вийде наступна серія? GET /3/tv/{tv_id} повертає next_episode_to_air з air_date, season_number і episode_number. Значення дорівнює null, якщо нічого не анонсовано. last_episode_to_air показує найновішу серію, що вже вийшла. ### Звідки беруться зображення серій? Кожна серія має still_path. Додайте його до https://img.amodb.dev/t/p/{size}, наприклад w300 для рядків списку. Зображення не потребують ключа. still_path може бути null, тож підготуйте заглушку. ## Пов'язані сторінки - [API сезонів і серій серіалів](https://amodb.dev/uk/tv-seasons-episodes/): API сезонів і серій серіалів з тими самими шляхами та JSON, що в TMDB v3. Читайте сезон з усіма серіями або одну серію з датою виходу, тривалістю та кадром. - [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги. - [API зображень і хост зображень](https://amodb.dev/uk/images-api/): API зображень фільмів зі шляхами TMDB v3: списки постерів, фонів, логотипів і кадрів проєкту, а потім завантаження з img.amodb.dev у 10 розмірах без ключа. - [API акторського складу та знімальної групи](https://amodb.dev/uk/credits/): API credits зі шляхами та JSON, як у TMDB v3. Отримайте акторський склад і знімальну групу фільмів, серіалів, сезонів і серій з полями order, department і job. - [API серіалів з даними про сезони та серії](https://amodb.dev/uk/tv-show-api/): API серіалів зі статусом, телемережами, сезонами, серіями та next_episode_to_air. JSON, сумісний із TMDB v3, 14 мовами, від 20 запитів на хвилину. - [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/episode-guide-api/