# 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/ru/tv-series/) и [сезоны и серии](https://amodb.dev/ru/tv-seasons-episodes/).

## Начало работы за 3 шага

1. Откройте страницу [цены](https://amodb.dev/ru/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/ru/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/ru/rate-limits/) и [ошибки](https://amodb.dev/ru/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/ru/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/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра.
- [API сезонов и серий сериала](https://amodb.dev/ru/tv-seasons-episodes/): API сезонов и серий сериала с теми же путями и JSON, что в TMDB v3. Читайте сезон со всеми сериями или одну серию с датой выхода, длительностью и кадром.
- [API списка серий](https://amodb.dev/ru/episode-guide-api/): API списка серий на эндпоинтах сезонов и серий TMDB v3: названия, даты выхода, длительность, кадры и группы серий для любого сериала, на 14 языках.
- [Компании и телесети](https://amodb.dev/ru/companies-networks/): Ищите киностудии и телесети по путям TMDB v3: читайте название, страну и логотип по ID, затем фильтруйте discover по ID компании или телесети.
- [Эндпоинты трендов и списков](https://amodb.dev/ru/trending-lists/): API фильмов в тренде с путями TMDB v3: чарты за день и неделю, а также списки идущих в кино, популярных, лучших и скорых фильмов и сериалов, кэш 30 минут.
- [Быстрый старт](https://amodb.dev/ru/quickstart/): Первый вызов amodb: получите ключ, запросите детали фильма через curl, JavaScript, Python, PHP или Go и загрузите постер с img.amodb.dev. Меньше 2 минут.

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