# Альтернатива TheTVDB API

> TheTVDB ориентирован на сериалы и хранит несколько порядков серий: эфирный, DVD и абсолютный. amodb покрывает сериалы, фильмы и людей одним ключом и сопоставляет TVDB ID со своим ID одним запросом. Он перечисляет группы серий шоу, но не их содержимое, поэтому альтернативная нумерация остается на TheTVDB.

## Что подойдет для проекта про сериалы

TheTVDB ориентирован на сериалы и хранит для шоу несколько порядков серий, включая эфирный, DVD и абсолютный, а доступ дает по модели ключа API. Прежде чем планировать коммерческий продукт, изучите условия лицензирования в их документации. Выбирайте amodb, если вам нужны сериалы, фильмы и люди с одним ключом, пути TMDB v3 и 14 языков. Выбирайте TheTVDB, если точная альтернативная нумерация находится в центре вашего приложения: amodb перечисляет группы серий шоу, но не отдает то, что внутри них.

## Как данные о сериалах соответствуют друг другу

Понятия совпадают, а названия различаются. Таблица охватывает то, что обычно читает приложение о сериалах.

| Задача                      | Подход TheTVDB                    | Вызов amodb                                                |
| --------------------------- | --------------------------------- | ---------------------------------------------------------- |
| Один сериал                 | Запись сериала по TVDB ID         | `GET /3/tv/1396` после поиска по `tvdb_id`                 |
| Список сезонов              | См. их документацию               | Массив `seasons` в сведениях о сериале                     |
| Один сезон с сериями        | См. их документацию               | `GET /3/tv/1396/season/1`                                  |
| Одна серия                  | См. их документацию               | `GET /3/tv/1396/season/1/episode/1`                        |
| Какие порядки существуют    | Эфирный, DVD и абсолютный порядки | `GET /3/tv/1396/episode_groups`                            |
| Серии внутри одного порядка | См. их документацию               | Не поддерживается, `/3/tv/episode_group/{id}` отвечает 404 |
| Следующая серия в эфире     | См. их документацию               | `next_episode_to_air` в сведениях о сериале                |

Поля серии используют имена TMDB: `air_date`, `episode_number`, `season_number`, `runtime` и `still_path`. Поля `external_ids` у сезонов и серий всегда равны null, поэтому TVDB ID отдельного сезона или серии из amodb прочитать нельзя. Связывайте записи по `season_number` и `episode_number`. Подробности на странице [сезоны и серии](https://amodb.dev/ru/tv-seasons-episodes/).

## Что возвращает список групп серий

Вызов списка показывает, какие порядки существуют для сериала. Серии внутри них он не возвращает.

| Поле            | Значение                                 |
| --------------- | ---------------------------------------- |
| `id`            | ID группы, строка                        |
| `name`          | Название порядка, например `DVD / PVOD`  |
| `description`   | Текст из источника, часто пустой         |
| `type`          | Число, которое показывает вид порядка    |
| `episode_count` | Число серий в порядке                    |
| `group_count`   | Число блоков в порядке, например сезонов |
| `network`       | Объект с телесетью или null              |

Вот настоящий ответ для Breaking Bad.

```json
{
  "id": 1396,
  "results": [
    {
      "description": "Seasons grouped as they appear on DVD, as well as paid video-on-demand services, such as Prime Video and YouTube.",
      "episode_count": 62,
      "group_count": 6,
      "id": "69f50757054263b7bc87e32a",
      "name": "DVD / PVOD",
      "network": null,
      "type": 3
    }
  ]
}
```

Одни шоу возвращают один эфирный порядок, другие несколько, а у некоторых массив `results` пуст. Проверьте шоу, которые важны вам. Поскольку содержимое группы не отдается, приложение, которому нужен DVD-номер или абсолютный номер каждой серии, получить его из amodb не сможет.

## Сравнение возможностей

| Функция                    | TheTVDB                                                | amodb                                                     |
| -------------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
| Модель оплаты              | Модель ключа API, лицензирование см. в их документации | Предоплата на периоды от 1 до 24 месяцев                  |
| Бесплатный тариф           | См. их документацию                                    | Нет, пробного периода тоже нет                            |
| Аутентификация             | Ключ API, порядок см. в их документации                | `api_key` или заголовок Bearer                            |
| Формат ответа              | JSON, см. их документацию                              | JSON в формате TMDB v3                                    |
| Языки                      | См. их документацию                                    | 14 языков интерфейса                                      |
| Фильмы                     | См. их документацию                                    | Да                                                        |
| Сериалы                    | Да, это основной профиль                               | Да, с сезонами и сериями                                  |
| Люди                       | См. их документацию                                    | Да                                                        |
| Изображения                | См. их документацию                                    | `img.amodb.dev`, ключ не нужен                            |
| Рейтинги                   | См. их документацию                                    | IMDb и еще четыре источника, где есть данные              |
| Лимит запросов             | См. их документацию                                    | 20, 40 или 120 в минуту на ключ                           |
| Коммерческое использование | Лицензирование см. в их документации                   | Платные тарифы, см. [цены](https://amodb.dev/ru/pricing/) |
| Совместимость              | Собственный API                                        | Чтение TMDB v3 и OMDb                                     |

## Чем отличается amodb

- **Один ключ на весь каталог.** Сериал, его актерский состав, трейлеры и фильм с тем же актером используют один базовый URL и один лимит.
- **Рейтинги рядом с гидом по сериям.** Параметр `append_to_response=ratings` в сведениях о сериале добавляет оценки IMDb и других источников за один запрос.
- **Понятные заголовки для контроля темпа.** `X-RateLimit-Remaining` и `X-RateLimit-Reset` показывают задаче синхронизации, сколько запросов осталось в окне 60 секунд.
- **Оригинальные названия сохраняются.** У сериала остается `original_name`, а `name` следует вашему `language`, что удобно, когда нужно показать название на родном языке.

## Когда TheTVDB подходит лучше

- **Порядок серий и есть продукт.** Если ваши пользователи спорят о DVD-порядке, эфирном и абсолютном, TheTVDB считает это ядром своей модели. amodb называет порядки шоу, но не возвращает их серии, а набор групп зависит от шоу.
- **Готовые интеграции.** Если ваш конвейер уже хранит ID TheTVDB и читает его порядки, оставьте эту часть и добавьте amodb для дополнительных данных.
- **Фокус на сериалах.** Если вы никогда не показываете фильмы и людей, источник, построенный вокруг сериалов, проще освоить.

## Миграция на amodb

Сопоставьте сохраненные TVDB ID один раз. После этого используйте ID amodb для каждого вызова. Эндпоинт find разрешает только ID сериалов. Его массивы `tv_season_results` и `tv_episode_results` всегда пусты, поэтому сезоны и серии сопоставляйте по номеру.

```js
const key = process.env.AMODB_KEY;
const headers = { Authorization: `Bearer ${key}` };
const base = 'https://api.amodb.dev/3';

async function getJson(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`${path} returned ${res.status}`);
  return res.json();
}

const found = await getJson('/find/81189?external_source=tvdb_id');
const show = found.tv_results[0];
console.log(show.id, show.name);

const groups = await getJson(`/tv/${show.id}/episode_groups`);
for (const g of groups.results) {
  console.log(g.name, g.type, g.episode_count);
}
```

Первый запрос возвращает Breaking Bad с id 1396. Второй перечисляет существующие порядки этого шоу вместе с их размерами. Чтобы сравнить нумерацию с той, что вы храните сейчас, читайте эфирный порядок из `/tv/{id}/season/{n}`, а любой альтернативный порядок оставьте на стороне TheTVDB. Проведите такую проверку на десяти самых популярных шоу, прежде чем переносить остальные.

Каждый вызов считается одним запросом в окне 60 секунд, а ответ 429 содержит `Retry-After`. См. [поиск по внешнему ID](https://amodb.dev/ru/find-by-external-id/) и [лимиты запросов](https://amodb.dev/ru/rate-limits/).

## Цены

amodb работает по предоплате без автоматического продления. Выберите 1, 3, 6, 12 или 24 месяца и один из трех тарифов на 20, 40 или 120 запросов в минуту. Длинные периоды дешевле на 10, 20, 30 или 40 процентов, а каждый тариф дает все данные. Бесплатного тарифа нет. Суммы указаны на странице [цены](https://amodb.dev/ru/pricing/).

## Вопросы и ответы

### Можно ли преобразовать TVDB ID в ID amodb?

Да. Вызовите /3/find/81189 с параметром external_source=tvdb_id. Массив tv_results содержит подходящий сериал, так что Breaking Bad вернется с id 1396. Сохраните пару и дальше используйте числовой id. Обратное тоже работает: /3/tv/1396/external_ids возвращает tvdb_id.

### Поддерживает ли amodb порядок серий DVD и абсолютный порядок?

Только частично. GET /3/tv/{id}/episode_groups перечисляет группы шоу с полями name, type, episode_count и group_count. Содержимое группы не отдается, а /3/tv/episode_group/{id} отвечает 404. Вы увидите, что порядок DVD существует, но прочитать его нумерацию нельзя.

### Бесплатен ли TheTVDB?

TheTVDB работает по модели ключа API, а условия лицензирования задает сам TheTVDB. Актуальную лицензию и возможную плату смотрите в их документации. amodb это платный API с предоплатой и без бесплатного тарифа.

### Получу ли я и данные о фильмах?

Да. Фильмы, люди, изображения, видео и переводы доступны с тем же ключом и тем же базовым URL, что и сериалы. Второй провайдер не нужен, если в приложении есть и то и другое.

### Как узнать, какая серия выйдет следующей?

Сведения о сериале содержат next_episode_to_air и last_episode_to_air, каждое с полями season_number, episode_number и air_date. У завершенного шоу следующая серия равна null. Сведения кэшируются на границе сети на 6 часов, поэтому опрашивайте не чаще нескольких раз в день.

## Связанные страницы

- [API сезонов и серий сериала](https://amodb.dev/ru/tv-seasons-episodes/): API сезонов и серий сериала с теми же путями и JSON, что в TMDB v3. Читайте сезон со всеми сериями или одну серию с датой выхода, длительностью и кадром.
- [Поиск по внешнему ID](https://amodb.dev/ru/find-by-external-id/): Найдите фильм, сериал или персону по ID IMDb, TVDB, Wikidata или Kinopoisk через эндпоинт find TMDB, а также прочитайте внешние ID и факты Wikidata о проекте.
- [API списка серий](https://amodb.dev/ru/episode-guide-api/): API списка серий на эндпоинтах сезонов и серий TMDB v3: названия, даты выхода, длительность, кадры и группы серий для любого сериала, на 14 языках.
- [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра.
- [Быстрый старт](https://amodb.dev/ru/quickstart/): Первый вызов amodb: получите ключ, запросите детали фильма через curl, JavaScript, Python, PHP или Go и загрузите постер с img.amodb.dev. Меньше 2 минут.
- [Лимиты запросов](https://amodb.dev/ru/rate-limits/): amodb ограничивает ключ запросами в минуту в скользящем окне 60 секунд: 20, 40 или 120 по тарифу. Читайте заголовки лимита и обрабатывайте 429 с Retry-After.

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