API zwiastunów filmowych

Pobieranie oficjalnego zwiastuna filmu

GET /3/movie/{movie_id}/videos zwraca wszystkie wideo powiązane z filmem. Każda pozycja ma type, flagę official, kod języka, znacznik czasu published_at oraz site i key, które identyfikują wideo. Zostaw pozycje, w których type to Trailer, a official to true, i masz zwiastun.

Dostajesz listę rekordów wideo, które możesz sam uporządkować, a nie strumień. Odpowiedź podaje nazwę wideo i miejsce, w którym leży, a twoja strona buduje odtwarzacz z site i key. Ten sam kształt wraca dla seriali. Ścieżki sezonów i odcinków odpowiadają pustą listą.

Jakie dane dostajesz

Pola każdego wideo:

Start w 3 krokach

1. Wybierz plan na stronie cennik. Każdy plan zwraca wszystkie dane, więc wybierasz według liczby żądań na minutę.
2. Utwórz klucz w panelu konta. Ma 32 małe znaki szesnastkowe.
3. Wywołaj GET /3/movie/{movie_id}/videos z kluczem w api_key albo w nagłówku Authorization: Bearer.

Przykładowe żądanie

Przykład prosi o wideo filmu Inception (ID 27205), sortuje je w kodzie i wypisuje najlepsze. Sortowanie stawia na początku zgodność języka, potem Trailer przed Teaser, potem oficjalne przed nieoficjalnymi, a na końcu najnowszy 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');

Przycięta odpowiedź: pierwsze 2 z 42 wideo. Lista zawiera wszystkie języki.

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

Wybór wideo do odtworzenia

Tytuł ma często kilka oficjalnych zwiastunów (pierwsze ogłoszenie, wersja finalna) obok teaserów i klipów. Sortuj je w stałej kolejności, żeby w miejscu zwiastuna nigdy nie wylądował zestaw wpadek z planu.

Remisy sortuj według published_at. Od najnowszych dostajesz ostatnią wersję, od najstarszych pierwsze ogłoszenie.

Języki zwiastunów

Wideo mają język w iso_639_1, a jeden tytuł może mieć zwiastuny w kilku. Inception ma 42 wideo w 9 językach. amodb zwraca je wszystkie w jednej odpowiedzi. Parametry language i include_video_language nie mają wpływu na endpointy wideo, więc język wybieraj w swoim kodzie.

W każdym kroku sortuj według typu i flagi official jak w przykładzie. Języki wideo wynikają z wgrania, a nie z 14 języków interfejsu wymienionych na stronie języki, więc zwiastun może mieć cs lub he.

Zwiastuny seriali

Zwiastun serialu leży pod /3/tv/1396/videos (Breaking Bad), gdzie jest 9 zwiastunów. Funkcja sortująca powyżej działa bez zmian, bo pola się nie zmieniają. Ścieżki sezonów i odcinków, takie jak /3/tv/1396/season/1/videos, odpowiadają 200 z pustą listą results, więc czytaj listę serialu. Pełną listę ścieżek zobacz w wideo i zwiastuny.

Budowanie karuzeli zwiastunów

Karuzela filmów aktualnie w kinach potrzebuje jednego wywołania listy i jednego wywołania na tytuł: GET /3/movie/now_playing (zobacz trendy i listy) plus dziesięć wywołań wideo daje 11 żądań na dziesięć tytułów. Wybrany key zapisuj obok ID filmu. Zwiastuny zmieniają się rzadko, więc odświeżaj zapisany wybór co kilka godzin albo gdy tytuł wraca do kin.

Jak wypada w porównaniu

Cennik

Plany są przedpłacone. Kupujesz 1, 3, 6, 12 lub 24 miesiące i dostajesz zniżkę 0, 10, 20, 30 lub 40 procent za dłuższe okresy. Nic nie odnawia się samo. Plany z 20, 40 i 120 żądaniami na minutę obsługują wszystkie endpointy z tej strony, więc ruchliwa karuzela zwiastunów to kwestia samego tempa. Nie ma darmowego planu ani wersji próbnej. Porównaj plany na stronie cennik.