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

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

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

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

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

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

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

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

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

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

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

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 видео. Список содержит все языки.

{
  "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"
    }
  ]
}

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

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

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

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

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

Внутри каждого шага ранжируйте по типу и флагу official, как в примере. Язык видео определяется загрузкой, а не 14 языками интерфейса со страницы языки, поэтому трейлер может быть cs или he.

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

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

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

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

Сравнение

Цены

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