# API за сериали, сезони и епизоди

> API за сериали връща сериал на GET /3/tv/{series_id} със статус, мрежи, списък със сезони и next_episode_to_air. Ендпойнтите за сезон и епизод добавят дати на излъчване, продължителност и кадри. JSON съвпада с TMDB v3, на 14 езика, с предплатени планове от 20, 40 или 120 заявки в минута.

## API за сериали със статус, сезони и следващ епизод

`GET /3/tv/{series_id}` връща сериал с неговите `status`, `networks`, списък `seasons`, `last_episode_to_air` и `next_episode_to_air`. Ендпойнтите за сезон и епизод добавят дати на излъчване, продължителност и кадри. amodb е независимо API, което работи по протокола на TMDB v3, така че клиент, написан за TMDB, работи, след като смените базовия URL на `https://api.amodb.dev/3`.

Какво получавате:

- Записи за сериали с брой сезони и епизоди, плюс дати на първото и последното излъчване.
- Низ `status` и флаг `in_production`.
- Мрежи с id, лога и държава на произход.
- Едно извикване на сезон, което връща всеки епизод на този сезон.
- Списъци със сериали, които се излъчват днес или в следващите 7 дни.

## Какви данни получавате

| От какво имате нужда      | Извикване                                                               | Ключови полета                                                                                |
| ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Запис на сериал           | `GET /3/tv/{series_id}`                                                 | `name`, `original_name`, `status`, `in_production`, `number_of_seasons`, `number_of_episodes` |
| Следващ и последен епизод | същото извикване                                                        | `next_episode_to_air`, `last_episode_to_air`                                                  |
| Един сезон                | `GET /3/tv/{series_id}/season/{season_number}`                          | `episodes`, `air_date`, `poster_path`                                                         |
| Един епизод               | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`, `overview`, `runtime`, `still_path`, `air_date`                                       |
| Мрежа                     | `GET /3/network/{network_id}`                                           | `name`, `headquarters`, `origin_country`                                                      |

Пълните списъци с полета са на страниците [сериали](https://amodb.dev/bg/tv-series/) и [сезони и епизоди](https://amodb.dev/bg/tv-seasons-episodes/).

## Започнете в 3 стъпки

1. Отворете [цени](https://amodb.dev/bg/pricing/) и изберете плана със скоростта на заявките, която ви трябва: 20, 40 или 120 в минута.
2. Създайте API ключ в личния си профил.
3. Изпратете `GET /3/tv/{series_id}` с `Authorization: Bearer YOUR_API_KEY` или добавете `api_key` като параметър на заявката.

## Пример със заявка

Скриптът чете Breaking Bad (id на сериала 1396), отпечатва статуса му и следващия епизод, после изброява сезон 1. Запазете го като `check.mjs` и го стартирайте с Node 18 или по-нов.

```bash
curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```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?language=en-US');
const next = show.next_episode_to_air;
console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`);
console.log(next
  ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}`
  : 'No upcoming episode is scheduled');

const season = await get('/tv/1396/season/1?language=en-US');
for (const ep of season.episodes) {
  console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`);
}
```

Съкратен отговор за сериал при `language=en-US`. Запазени са само някои полета, а `seasons` показва първите 2 от 6 записа. Някои имена в тези данни не следват `language`: името на сезон 0 е на китайски, а `name` в `last_episode_to_air` е на иврит.

```json
{
  "first_air_date": "2008-01-20",
  "id": 1396,
  "in_production": false,
  "last_air_date": "2013-09-29",
  "last_episode_to_air": {
    "air_date": "2013-09-29",
    "episode_number": 16,
    "episode_type": "standard",
    "id": 62161,
    "name": "פלינה",
    "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.",
    "production_code": "",
    "runtime": 56,
    "season_number": 5,
    "show_id": 1396,
    "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg",
    "vote_average": 0,
    "vote_count": 0
  },
  "name": "Breaking Bad",
  "next_episode_to_air": null,
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "original_name": "Breaking Bad",
  "seasons": [
    {
      "air_date": "2009-02-17",
      "episode_count": 9,
      "id": 3577,
      "name": "特别篇",
      "overview": "",
      "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg",
      "season_number": 0,
      "vote_average": 0
    },
    {
      "air_date": "2008-01-20",
      "episode_count": 7,
      "id": 3572,
      "name": "Season 1",
      "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagn...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "status": "Ended"
}
```

## Как да четете статуса и следващия епизод

Низът `status` ви казва как да обозначите сериала. `next_episode_to_air` е обект само докато има насрочен епизод, така че между сезоните е null, както и след края. Проверете `status`, преди да покажете „приключил“.

| `status`         | Значение                    | Какво да покажете                                                        |
| ---------------- | --------------------------- | ------------------------------------------------------------------------ |
| Returning Series | Очакват се още епизоди      | Следващата дата на излъчване, ако обектът съществува, иначе „продължава“ |
| In Production    | Снима се, още не е в ефира  | „В производство“                                                         |
| Planned          | Само обявен                 | „Планиран“                                                               |
| Pilot            | Съществува само пилот       | „Пилот“                                                                  |
| Ended            | Излъчването е приключило    | „Приключил“ и `last_air_date`                                            |
| Canceled         | Спрян преди планирания край | „Спрян“                                                                  |

Полета в `next_episode_to_air` и `last_episode_to_air`: `air_date`, `season_number`, `episode_number`, `episode_type`, `id`, `show_id`, `name`, `overview`, `runtime` и `still_path`. Низът `status` може да е празен и при няколко заглавия, затова дръжте готов неутрален етикет.

Детайлите се кешират на edge за 6 часа, така че искането на същия сериал повече от четири пъти на ден връща същото тяло. Проверявайте следваните сериали веднъж или два пъти на ден и обновявайте този, който потребителят отвори.

## Сезони, епизоди и какво е в ефира

Сезон 0, когато сериалът има такъв, съдържа специалните епизоди. Обикновените сезони започват от 1.

| Извикване                                      | Какво връща                                  | Параметри                                         |
| ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------- |
| `GET /3/tv/{series_id}/season/{season_number}` | Запис на сезон с масив `episodes`            | `language`, `append_to_response`                  |
| `GET /3/tv/airing_today`                       | Сериали с епизод в ефира днес                | `page`, `language`                                |
| `GET /3/tv/on_the_air`                         | Сериали в ефира през следващата седмица      | `page`, `language`                                |
| `GET /3/discover/tv`                           | Сериали, филтрирани по мрежа, статус и други | `with_networks`, `with_status`, `sort_by`, `page` |

Списъците и резултатите от discover се кешират за 30 минути, така че една заявка на половин час стига за значка „скоро в ефира“. Съпоставете върнатите id със сериалите, които следят потребителите ви. Детайлите за сезони и епизоди са на страницата [справочник по епизоди](https://amodb.dev/bg/episode-guide-api/).

## Списък за следене с обратно броене

Екран „сериали, които следя“ иска по едно запазено id на сериал и малка дневна задача.

1. Запазете `id` на сериала, когато потребител започне да го следи.
2. Веднъж дневно викайте `/3/tv/{series_id}` за всяко следено id и пазете `status`, `next_episode_to_air` и `last_air_date`.
3. Когато `next_episode_to_air` е обект, показвайте `air_date` като дата. Тя не носи час от денонощието и часова зона, затова не броете обратно до минутата.
4. Когато е null, а `status` е Returning Series, показвайте „новият сезон не е насрочен“.
5. Викайте сезона само когато потребител отвори сериала, защото е най-големият отговор.

404 със `status_code` 34 означава, че id е непознато, а 429 означава, че сте надхвърлили заявките в минута: изчакайте `Retry-After` секунди. При 200 следени сериала един дневен преглед са 200 заявки, около десет минути при 20 заявки в минута. Вижте [лимити на заявките](https://amodb.dev/bg/rate-limits/) и [грешки](https://amodb.dev/bg/errors/).

## Как се сравнява

| Възможност                    | Сами да обработвате страници                | API за метаданни с безплатен план    | amodb                                                   |
| ----------------------------- | ------------------------------------------- | ------------------------------------ | ------------------------------------------------------- |
| Структура на сезони и епизоди | Възстановява се от оформлението на страници | Различно, вижте документацията       | Извикване за сезон с масив `episodes`                   |
| Дата на следващото излъчване  | Разчита се от страница с програма           | Различно, вижте документацията       | `next_episode_to_air`, null, когато нищо не е насрочено |
| Статус на сериала             | Свободен текст на страница                  | Различно, вижте документацията       | Низ `status` и флаг `in_production`                     |
| Излъчвани тази седмица        | Обработка на програма                       | Различно, вижте документацията       | `/3/tv/on_the_air` и `/3/tv/airing_today`               |
| Езици                         | Каквото предлага страницата                 | Различно                             | 14, избират се с `language`                             |
| Условия за достъп             | Важат условията на сайта                    | Безплатен план с условия за ползване | Платен, предплатен, без безплатен план                  |

## Цени

Плащате веднъж за 1, 3, 6, 12 или 24 месеца. По-дългите периоди дават отстъпка 10, 20, 30 или 40 процента и нищо не се подновява автоматично. Всеки план получава всички данни за сериали, като единствената разлика е 20, 40 или 120 заявки в минута. Вижте [цени](https://amodb.dev/bg/pricing/), създайте ключ и първото ви извикване за сериал струва една заявка.

## Въпроси и отговори

### Как да разбера дали сериалът още се излъчва?

Четете status на /3/tv/{id}. Returning Series означава, че се очакват още епизоди, а Ended и Canceled означават, че няма. Полето next_episode_to_air съдържа следващия насрочен епизод и е null, когато нищо не е насрочено.

### Мога ли да взема всички епизоди на сериал с една заявка?

По един сезон на извикване. GET /3/tv/{id}/season/{n} връща всички епизоди на сезона в масив episodes, така че сериал с пет сезона изисква пет извиквания за сезони плюс едно за сериала.

### Какво получавам за мрежа?

Масивът networks на сериал изброява id, name, logo_path и origin_country. GET /3/network/{id} добавя детайли, а with_networks в /3/discover/tv изброява сериалите на една мрежа.

### Мога ли да изброя сериалите, които се излъчват днес?

Да. /3/tv/airing_today изброява сериали с епизод в ефира днес, а /3/tv/on_the_air покрива следващите 7 дни. И двата са странирани, приемат language и стоят в edge кеша 30 минути.

### Има ли безплатен план за API за сериали?

Няма безплатен план и пробен период. Плащате предварително за 1, 3, 6, 12 или 24 месеца и нищо не се подновява само. Всеки план връща всички данни, а плановете се различават само по заявките в минута.

## Свързани страници

- [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане.
- [API за сезони и епизоди на сериали](https://amodb.dev/bg/tv-seasons-episodes/): API за сезони и епизоди със същите пътища и JSON като TMDB v3. Четете сезон с всичките му епизоди или един епизод с дата на излъчване, продължителност и кадър.
- [API за справочник по епизоди](https://amodb.dev/bg/episode-guide-api/): API за справочник по епизоди с ендпойнтите за сезон и епизод на TMDB v3: имена, дати, продължителност, кадри и групи епизоди за всеки сериал, на 14 езика.
- [Компании и мрежи](https://amodb.dev/bg/companies-networks/): Търсете продуцентски компании и мрежи с пътища на TMDB v3. Четете име, държава и лого по id, после филтрирайте discover по компания или мрежа.
- [Ендпойнти за тенденции и списъци](https://amodb.dev/bg/trending-lists/): API за филми в тенденция с пътища на TMDB v3: класации за ден и седмица, списъци в кината, популярни, най-добри и предстоящи, кеш 30 минути.
- [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути.

Обновено: 2026-10-18. Source: https://amodb.dev/bg/tv-show-api/