# API за сезони и епизоди на сериали > Един сезон с всичките му епизоди се чете на GET /3/tv/{series_id}/season/{season_number}, а отделен епизод е едно ниво по-дълбоко. JSON съвпада с TMDB v3 с air_date, episode_number, runtime и still_path. Всеки епизод носи crew и guest_stars, сезон 0 съдържа специалните епизоди, а append_to_response добавя credits, images и videos. ## Ендпойнт `GET /3/tv/{series_id}/season/{season_number}` ```bash curl "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Отговор: ```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 of lung cancer, he decides to team up with a former student and create a top of the line crystal meth in a used RV, to provide for his family once he is gone.", "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" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee313280006e8", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.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" }, { "character": "Jock", "credit_id": "52542275760ee313280006b4", "order": 500, "adult": false, "gender": 2, "id": 1216132, "known_for_department": "Acting", "name": "Aaron Hill", "original_name": "Aaron Hill", "popularity": 1.6521, "profile_path": "/rNp31SeoVqSQU6OZWxZUhGwAgyq.jpg" }, { "character": "Dr. Belknap", "credit_id": "52725cb1760ee3044d0b9984", "order": 502, "adult": false, "gender": 2, "id": 161591, "known_for_department": "Acting", "name": "Gregory Chase", "original_name": "Gregory Chase", "popularity": 0.5435, "profile_path": "/gNdodev00CROpXuAh5EFmkWTVOo.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 more complicated with the flip of a coin. Walt's wife, Skyler, becomes suspicious of Walt's strange behavior.", "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" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.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" }, { "character": "Ob-Gyn", "credit_id": "63012c9c5f4b73008267ba53", "order": 682, "adult": false, "gender": 0, "id": 1448105, "known_for_department": "Acting", "name": "Shane Marinson", "original_name": "Shane Marinson", "popularity": 0, "profile_path": null }, { "character": "Ben", "credit_id": "63012d2111c066007cbc37b1", "order": 683, "adult": false, "gender": 0, "id": 3670897, "known_for_department": "Acting", "name": "Jason Byrd", "original_name": "Jason Byrd", "popularity": 0, "profile_path": null } ] }, { "air_date": "2008-02-10", "episode_number": 3, "episode_type": "standard", "id": 62087, "name": "...And the Bag's in the River", "overview": "Walter fights with Jesse over his drug use, causing him to leave Walter alone with their captive, Krazy-8. Meanwhile, Hank has a scared straight moment with Walter Jr. after his aunt discovers he has been smoking pot. Also, Skylar is upset...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/2kBeBlxGqBOdWlKwzAxiwkfU5on.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" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.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" }, { "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" }, { "character": "Carmen Molina", "credit_id": "52542273760ee31328000676", "order": 643, "adult": false, "gender": 1, "id": 115688, "known_for_department": "Acting", "name": "卡门·塞兰诺", "original_name": "卡门·塞兰诺", "popularity": 1.1342, "profile_path": "/nzJEe2UqvvMIBJZP1aeFEj4EunN.jpg" } ] } ], "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.", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Вземане на сезон `GET /3/tv/{series_id}/season/{season_number}` връща един сезон и пълния му масив `episodes` в един отговор. Номерата на сезоните започват от `1`, а `0` е запазен за специални епизоди. Вземете id на сериала и номерата на сезоните от записа [сериали](https://amodb.dev/bg/tv-series/). Примерът чете сезон 1 на Breaking Bad. Кодът отпечатва по един ред за епизод. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/tv/1396/season/1?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 season = await res.json(); for (const ep of season.episodes) { console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396/season/1", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() season = r.json() for ep in season["episodes"]: print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?") ``` ```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"); } $season = json_decode($body, true); foreach ($season['episodes'] as $ep) { printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Season struct { Name string `json:"name"` Episodes []struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` } `json:"episodes"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?language=en-US", 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 Season if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } for _, e := range s.Episodes { fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime) } } ``` ### Параметри | Параметър | Къде | Задължителен | Описание | | -------------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------- | | `series_id` | път | да | Числов id на сериала, например `1396`. | | `season_number` | път | да | Цял номер на сезона. `0` връща специалните епизоди. | | `api_key` | заявка | един от двата | Вашият ключ. Ползвайте него или заглавката `Authorization: Bearer`. | | `language` | заявка | не | Таг на TMDB, например `en-US` или `fr-FR`. Поддържат се 14 основни езика. По подразбиране `en-US`. | | `append_to_response` | заявка | не | Стойности на ниво сезон: `credits`, `external_ids`, `images`, `videos`. Другите имена се игнорират. | ### Полета на отговора | Поле | Тип | Бележки | | --------------------- | ------------ | ------------------------------------------------------ | | `id`, `season_number` | цяло число | Id на сезона и номерът му в сериала. | | `name`, `overview` | низ | Локализиран текст, празен, когато няма превод. | | `air_date` | низ или null | Дата на първия епизод, `YYYY-MM-DD`. | | `poster_path` | низ или null | Добавя се към `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | число | Обобщена потребителска оценка за сезона. | | `episodes` | масив | Всеки епизод, с полетата, изброени в следващия раздел. | ### Примерен отговор `GET /3/tv/1396/season/1?language=en-US`. Сезонът има 7 епизода, затова `episodes` е съкратен до един запис, а масивите `crew` и `guest_stars` на този запис са пропуснати: ```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 of lung cancer, he decides to...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0 } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` Всеки епизод в отговора за сезон носи и масиви `crew` и `guest_stars` с формата на записа, описана на страницата [участници](https://amodb.dev/bg/credits/). `runtime` може да е null за неизлъчен епизод. ## Вземане на епизод `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` връща един епизод. Отговорът за сезон вече съдържа всеки епизод с `crew` и `guest_stars`, затова ползвайте този ендпойнт, за да обновите един запис, без да зареждате отново сезона. Приема `language` и `append_to_response` със `credits`, `external_ids`, `images`, `translations` и `videos`. Заявка като `/3/tv/1396/season/1/episode/1?append_to_response=credits` струва една заявка. | Поле | Тип | Бележки | | --------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `id` | цяло число | Id на епизода. | | `show_id` | цяло число | Id на сериала. Присъства в отговора за сезон и в указателите на сериала, но не и в отговора за единичен епизод. | | `season_number`, `episode_number` | цяло число | Позиция в сериала. Ползвайте ги, за да построите пътя на заявката. | | `name`, `overview` | низ | Локализиран текст. | | `air_date` | низ или null | Само дата, без час и часова зона. Null, когато е ненасрочен. | | `episode_type` | низ | `standard` за обикновени епизоди. За да познаете финал, сравнете `episode_number` с `episode_count` на този сезон в записа на сериала. | | `runtime` | цяло число или null | Минути. | | `production_code` | низ | Код на студиото, често празен. | | `still_path` | низ или null | Кадър от епизода. Ползвайте `w300` или `original` от `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | число, цяло число | Обобщена потребителска оценка. | | `crew`, `guest_stars` | масив | Участниците в този епизод, вижте [участници](https://amodb.dev/bg/credits/). | ## Следващ и последен епизод в записа на сериала Ендпойнтът за сериал връща `next_episode_to_air` и `last_episode_to_air`. Всеки от тях е кратко описание на епизод с полетата по-горе, плюс `show_id` и без `crew` и `guest_stars`. Следващият е null за приключили сериали и за продължаващи сериали без потвърдена дата. Примерът чете South Park, продължаващ сериал. ```js const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const next = (await res.json()).next_episode_to_air; console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode'); ``` За обратно броене сравнете `air_date` с местната дата на зрителя. Стойността не носи час от денонощието, затова показвайте дата, а не часовник. ## Подресурси на сезон и епизод Пътищата за сезон и епизод имат собствени подресурси. Няколко от тях днес връщат празни данни. | Метод и път | Какво връща | | --------------------------------------------------------- | ----------------------------------------------------------------- | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` и `crew` за сезона | | `GET /tv/{series_id}/season/{season_number}/images` | `id` и празен масив `posters` | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` и празен масив `results` | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` плюс `tvdb_id`, `wikidata_id` и други id, всички null | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` и празен масив `translations` | | `GET .../episode/{episode_number}/credits` | `id`, празен `cast`, `crew` и `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` и масив `stills` с кадъра на епизода | | `GET .../episode/{episode_number}/videos` | `id` и празен масив `results` | | `GET .../episode/{episode_number}/external_ids` | `id` плюс `imdb_id`, `tvdb_id` и други id, всички null | | `GET .../episode/{episode_number}/translations` | `id` и масив `translations` със заглавие и описание за всеки език | Участниците в сезон и епизод са описани на страницата [участници](https://amodb.dev/bg/credits/), а кадрите на страницата [изображения](https://amodb.dev/bg/images-api/). amodb не предлага пътищата `changes` на TMDB и ендпойнт за епизодите на една група епизоди. ## Грешки | HTTP | status_code | Кога | | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Ключът липсва или е грешен. | | 402 | 36 | Периодът на плана е изтекъл. | | 404 | 34 | Сериалът, сезонът или епизодът не съществува, например сезон `0` при сериал без специални епизоди, или пътят не се предлага. | | 405 | 37 | Извикали сте метод за запис. | | 429 | 25 | Надхвърлен е лимитът на заявки в минута. Изчакайте `Retry-After` секунди. | Вижте [грешки](https://amodb.dev/bg/errors/) за пълния формат на тялото и [лимити на заявките](https://amodb.dev/bg/rate-limits/) за прозорците. ## Практически бележки - Сезоните и епизодите се кешират за 6 часа. Докато сериалът се излъчва, четете текущия сезон отново веднъж-два пъти на ден. - Сериал с 10 сезона изисква 10 извиквания за сезони. При плана с 20 заявки в минута това е половината от лимита за една минута, а повторно изпълнение в рамките на 6 часа се обслужва от edge кеша. - Неизлъчен епизод може да има `air_date` със стойност null, `runtime` със стойност null и празен `overview`. Показвайте заместител вместо да се чупите. - Кадрите са широки изображения, а не постери. Искайте `w300` за списъци и `original` само когато ви трябва изглед в пълен размер. ## Въпроси и отговори ### Как да изброя всички епизоди на сериал? Прочетете number_of_seasons от записа на сериала, после извикайте ендпойнта за сезон по веднъж за всеки номер на сезон. Всеки отговор за сезон носи пълния масив episodes, така че сериал с пет сезона изисква пет заявки. ### Какво означава сезон с номер 0? Сезон 0 съдържа специални материали като закулисни клипове и обобщения. Той съществува само когато сериалът има такива, а сериал без тях връща 404 със status_code 34 за сезон 0. ### Защо air_date е null при някои епизоди? Епизодът е обявен, но още няма потвърдена дата. Третирайте null като ненасрочен и проверете next_episode_to_air в записа на сериала за следващия епизод с дата. ### Мога ли да получа DVD или абсолютен ред на епизодите? Не като отделен списък. GET /3/tv/{series_id}/episode_groups назовава редовете, които сериалът има, но amodb не предлага ендпойнт, който връща епизодите на една група. Ендпойнтът за сезон дава стандартния ред. ## Свързани страници - [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане. - [API за участниците](https://amodb.dev/bg/credits/): API за участници със същите пътища и JSON като TMDB v3. Актьори и екип за филми, сериали, сезони и епизоди, с полета order, department и job. - [API за изображения и хост за изображения](https://amodb.dev/bg/images-api/): API за изображения на филми с пътища на TMDB v3: списъци с постери, фонови изображения, лога и кадри, после зареждане от img.amodb.dev в 10 размера без ключ. - [API за справочник по епизоди](https://amodb.dev/bg/episode-guide-api/): API за справочник по епизоди с ендпойнтите за сезон и епизод на TMDB v3: имена, дати, продължителност, кадри и групи епизоди за всеки сериал, на 14 езика. - [Лимити на заявките](https://amodb.dev/bg/rate-limits/): amodb ограничава всеки ключ по заявки в минута в плъзгащ се прозорец от 60 секунди: 20, 40 или 120. Заглавки за лимита и обработка на 429 с Retry-After. - [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути. Обновено: 2026-10-18. Source: https://amodb.dev/bg/tv-seasons-episodes/