# API трейлеров фильмов

> API трейлеров фильмов работает через GET /3/movie/{movie_id}/videos на api.amodb.dev. Каждое видео содержит тип, флаг official, язык и дату публикации, поэтому нужный официальный трейлер выбирается за один проход по списку. Сериалы возвращают ту же структуру. Пути и JSON совпадают с TMDB v3.

## Как получить официальный трейлер фильма

`GET /3/movie/{movie_id}/videos` возвращает все видео, привязанные к фильму. У каждого элемента есть `type`, флаг `official`, код языка, метка времени `published_at`, а также `site` и `key`, которые идентифицируют видео. Оставьте элементы, где `type` равен `Trailer`, а `official` равен `true`, и трейлер у вас есть.

Вы получаете список записей о видео, которые можете ранжировать сами, а не поток. Ответ называет видео и место, где оно размещено, а плеер на вашей странице строится из `site` и `key`. Для сериалов приходит та же структура. Пути сезонов и серий отвечают пустым списком.

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

| Эндпоинт                                                                   | Что возвращает                                                             |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}/videos`                                           | Трейлеры, тизеры, клипы, ролики о создании фильма, закулисные кадры и ляпы |
| `GET /3/tv/{tv_id}/videos`                                                 | Тот же список для сериала                                                  |
| `GET /3/tv/{tv_id}/season/{season_number}/videos`                          | Всегда пустой список `results`                                             |
| `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | Всегда пустой список `results`                                             |
| `GET /3/movie/{movie_id}` с `append_to_response=videos`                    | Детали и видео в одном запросе                                             |

Поля каждого видео:

| Поле                      | Тип     | Назначение                                                                                                      |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `type`                    | string  | Вид видео: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` или `Bloopers`, как на странице видео |
| `official`                | boolean | `true`, если видео помечено как официальное                                                                     |
| `iso_639_1`, `iso_3166_1` | string  | Коды языка и страны видео                                                                                       |
| `key`, `site`             | string  | Идентификатор видео и название сайта, где оно размещено, у всех просмотренных видео это `YouTube`               |
| `size`                    | integer | Вертикальное разрешение, у всех просмотренных видео `1080`                                                      |
| `published_at`            | string  | Метка времени ISO 8601, удобна для сортировки от новых к старым                                                 |
| `name`, `id`              | string  | Название видео и его ID, совпадающий со строкой `key`                                                           |

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

1. Выберите тариф на странице [цены](https://amodb.dev/ru/pricing/). Любой тариф возвращает все данные, поэтому выбирайте по числу запросов в минуту.
2. Создайте ключ в личном кабинете. Это 32 символа шестнадцатеричной записи в нижнем регистре.
3. Вызовите `GET /3/movie/{movie_id}/videos`, передав ключ в `api_key` или в заголовке `Authorization: Bearer`.

## Пример запроса

Пример запрашивает видео фильма Inception (ID `27205`), ранжирует их в коде и печатает лучшее. При ранжировании сначала идут совпадения по языку, затем `Trailer` перед `Teaser`, затем официальные перед неофициальными, затем самый новый `published_at`.

```bash
curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');
```

Сокращенный ответ: первые 2 из 42 видео. Список содержит все языки.

```json
{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"
    },
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "35mm Theatrical Trailer #3",
      "key": "cdx31ak4KbQ",
      "site": "YouTube",
      "size": 1080,
      "type": "Trailer",
      "official": false,
      "published_at": "2022-03-07T06:00:19Z",
      "id": "cdx31ak4KbQ"
    }
  ]
}
```

## Как выбрать видео для воспроизведения

У тайтла часто несколько официальных трейлеров (первый анонс, финальная версия) рядом с тизерами и клипами. Ранжируйте их в фиксированном порядке, чтобы в слоте трейлера никогда не оказалась нарезка ляпов.

| Приоритет | Фильтр                                 | Типичное применение                                           |
| --------- | -------------------------------------- | ------------------------------------------------------------- |
| 1         | `Trailer`, официальный, язык совпадает | Видео для воспроизведения                                     |
| 2         | `Trailer`, неофициальный               | Региональные или любительские загрузки, когда официальных нет |
| 3         | `Teaser`, официальный                  | Короткие ролики до премьеры                                   |
| 4         | `Clip`, `Featurette`                   | Запасной вариант, чтобы слот не оставался пустым              |
| пропуск   | `Behind the Scenes`, `Bloopers`        | Показывайте в отдельном списке дополнительных материалов      |

Равные по приоритету видео сортируйте по `published_at`. От новых к старым вы получите последнюю версию, от старых к новым первый анонс.

## Языки трейлеров

Язык видео задается через `iso_639_1`, и у одного тайтла могут быть трейлеры на нескольких языках. У Inception 42 видео на 9 языках. amodb возвращает их все в одном ответе. Параметры `language` и `include_video_language` не влияют на эндпоинты видео, поэтому язык выбирайте в своем коде.

| Шаг | Что делать                                                                           |
| --- | ------------------------------------------------------------------------------------ |
| 1   | Оставьте видео, у которых `iso_639_1` совпадает с языком пользователя, например `ru` |
| 2   | Если совпадений нет, оставьте `en`                                                   |
| 3   | Если и их нет, оставьте остальные                                                    |

Внутри каждого шага ранжируйте по типу и флагу `official`, как в примере. Язык видео определяется загрузкой, а не 14 языками интерфейса со страницы [языки](https://amodb.dev/ru/languages/), поэтому трейлер может быть `cs` или `he`.

## Трейлеры сериалов

Трейлер сериала находится по адресу `/3/tv/1396/videos` (Breaking Bad), там 9 трейлеров. Функция ранжирования выше работает без изменений, потому что поля не меняются. Пути сезонов и серий, например `/3/tv/1396/season/1/videos`, отвечают 200 с пустым списком `results`, поэтому читайте список сериала. Полный список путей смотрите на странице [видео и трейлеры](https://amodb.dev/ru/videos-trailers/).

## Как собрать ленту трейлеров

Для ленты фильмов в прокате нужен один запрос списка и по одному запросу на каждый тайтл: `GET /3/movie/now_playing` (см. [списки трендов](https://amodb.dev/ru/trending-lists/)) плюс десять запросов видео дают 11 запросов на десять тайтлов. Храните выбранный `key` рядом с ID фильма. Трейлеры меняются редко, поэтому обновляйте сохраненный выбор раз в несколько часов или при повторном прокате тайтла.

## Сравнение

| Возможность          | Парсинг страниц самостоятельно  | API метаданных с бесплатным тарифом | amodb                                                               |
| -------------------- | ------------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
| Флаг official        | Угадывать по заголовку страницы | Уточняйте в их документации         | Булево поле `official` у каждого видео                              |
| Фильтр по типу видео | Разбирать текст                 | Уточняйте в их документации         | Шесть значений `type`                                               |
| Выбор языка          | Одна локаль на страницу         | Уточняйте в их документации         | `iso_639_1` и `iso_3166_1` у каждого видео, фильтрация в вашем коде |
| Сериалы и серии      | Отдельные страницы для обхода   | Уточняйте в их документации         | Сериалы используют тот же эндпоинт, списки сезонов и серий пусты    |
| Поддержка            | Ломается при смене разметки     | Зависит от провайдера               | Одна стабильная структура JSON                                      |
| Условия              | Риск на вас                     | Уточняйте в их условиях             | Платные тарифы, см. [цены](https://amodb.dev/ru/pricing/)           |

## Цены

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

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

### Как получить официальный трейлер фильма?

Вызовите GET /3/movie/{movie_id}/videos, оставьте элементы, где type равен Trailer и official равен true, затем отсортируйте по published_at. Первый элемент будет самым новым официальным трейлером. Если трейлера нет, используйте Teaser как запасной вариант.

### Возвращает ли API видеофайл или поток?

Нет. Он возвращает метаданные каждого видео: name, type, site, key, size, язык и даты. Ссылку для плеера вы собираете из site и key или встраиваете видео на своей странице. Постеры и кадры отдает img.amodb.dev.

### Как получить трейлеры на нужном языке?

Эндпоинт videos возвращает все языки в одном ответе и игнорирует параметры language и include_video_language. Фильтруйте по iso_639_1 в своем коде, например сначала ru, затем en, затем остальные. У Inception есть видео на 9 языках.

### Есть ли трейлеры для сериалов и серий?

Для сериалов да: используйте /3/tv/{tv_id}/videos. Поля те же, поэтому код ранжирования, написанный для фильмов, работает без изменений. Пути видео для сезона и серии отвечают пустым массивом results, поэтому берите список сериала.

### Сколько запросов тратит поиск трейлера?

Один запрос на тайтл. С append_to_response=videos трейлер приходит внутри запроса деталей, поэтому детали плюс трейлер остаются одним запросом из ваших 20, 40 или 120 запросов в минуту.

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

- [API видео и трейлеров](https://amodb.dev/ru/videos-trailers/): API видео фильмов с путями TMDB v3: список трейлеров, тизеров, клипов и фичереток фильма или сериала, фильтрация по типу и языку в вашем коде.
- [API деталей фильма](https://amodb.dev/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках.
- [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра.
- [Эндпоинты трендов и списков](https://amodb.dev/ru/trending-lists/): API фильмов в тренде с путями TMDB v3: чарты за день и неделю, а также списки идущих в кино, популярных, лучших и скорых фильмов и сериалов, кэш 30 минут.
- [Языки](https://amodb.dev/ru/languages/): amodb отдает названия, описания и имена на 14 языках. Передайте в language тег в стиле TMDB, например ru-RU или pt-BR; другие теги откатываются на английский.
- [Быстрый старт](https://amodb.dev/ru/quickstart/): Первый вызов amodb: получите ключ, запросите детали фильма через curl, JavaScript, Python, PHP или Go и загрузите постер с img.amodb.dev. Меньше 2 минут.

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