# 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/be/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 запытаў. Дэталі кэшуюцца на edge на 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/be/trending-lists/) кэшуюцца на 30 хвілін. ## Кадры і працягласць Выкарыстоўвайце `w185` або `w300` для радкоў спісу і `original` для поўнага памеру. Памеры кадраў: `w92`, `w185`, `w300` і `original`. У эпізода можа не быць кадра, таму паказвайце запаўняльнік, калі `still_path` роўны `null`. Хост выяў не патрабуе ключа, гл. [выявы](https://amodb.dev/be/images-api/). `runtime` вымяраецца ў хвілінах і можа быць `null`. Каб паказаць час марафона для сезона, складзіце `runtime` усіх `episodes` і лічыце `null` за 0. Дадайце `append_to_response=credits,images` на шляху аднаго эпізода, каб атрымаць аб’ект `credits` і спіс `stills`. Масіў `cast` эпізода пусты, а людзі знаходзяцца ў `crew` і `guest_stars`. Падрабязнасці на старонках [сезоны і эпізоды](https://amodb.dev/be/tv-seasons-episodes/) і [удзельнікі](https://amodb.dev/be/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/be/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 пералічвае іх з name, type і колькасцю эпізодаў. 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/be/tv-seasons-episodes/): API сезонаў і эпізодаў з тымі ж шляхамі і JSON, што ў TMDB v3. Чытайце сезон з усімі эпізодамі або адзін эпізод з датай эфіру, працягласцю і кадрам. - [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду. - [API выяў і хост выяў](https://amodb.dev/be/images-api/): API выяў фільмаў з шляхамі TMDB v3: спісы постэраў, фонавых выяў, лагатыпаў і кадраў назвы, а потым загрузка з img.amodb.dev у 10 памерах без ключа. - [API ўдзельнікаў](https://amodb.dev/be/credits/): API ўдзельнікаў з тымі ж шляхамі і JSON, што ў TMDB v3. Акцёры і здымачная група фільмаў, серыялаў, сезонаў і эпізодаў з палямі order, department і job. - [API серыялаў, сезонаў і эпізодаў](https://amodb.dev/be/tv-show-api/): API серыялаў са статусам, тэлеканаламі, сезонамі, эпізодамі і next_episode_to_air. JSON, сумяшчальны з TMDB v3, на 14 мовах, ад 20 запытаў у хвіліну. - [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/episode-guide-api/