API per i trailer dei film

Ottenere il trailer ufficiale di un film

GET /3/movie/{movie_id}/videos restituisce tutti i video collegati a un film. Ogni elemento ha un type, un flag official, un codice lingua, un timestamp published_at, e il site e la key che identificano il video. Tieni gli elementi in cui type è Trailer e official è true, e hai il tuo trailer.

Ottieni un elenco di record video che ordini tu, non uno stream. La risposta nomina il video e dice dove si trova, e la tua pagina costruisce il player da site e key. La stessa struttura torna per le serie TV. I percorsi di stagioni ed episodi rispondono con una lista vuota.

Quali dati ottieni

Campi di ogni video:

Parti in 3 passaggi

1. Scegli un piano nella pagina dei prezzi. Ogni piano restituisce tutti i dati, quindi scegli in base alle richieste al minuto.
2. Crea una chiave nella dashboard del tuo account. È di 32 caratteri esadecimali minuscoli.
3. Chiama GET /3/movie/{movie_id}/videos con la chiave in api_key o in un header Authorization: Bearer.

Esempio di richiesta

L'esempio chiede i video di Inception (id 27205), li ordina nel codice e stampa il migliore. L'ordinamento mette prima le corrispondenze di lingua, poi Trailer prima di Teaser, poi quelli ufficiali prima dei non ufficiali, poi il published_at più recente.

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');

Risposta ridotta: i primi 2 dei 42 video. La lista contiene tutte le lingue.

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

Scegliere quale video riprodurre

Un titolo ha spesso più trailer ufficiali (un primo annuncio, una versione finale) accanto a teaser e clip. Ordinali con una sequenza fissa così la pagina non finisce mai con un video di fuori onda al posto del trailer.

Spareggia i pari con published_at. Dal più recente dà l'ultima versione, dal più vecchio dà il primo annuncio.

Lingue dei trailer

I video sono etichettati con una lingua tramite iso_639_1, e un titolo può avere trailer in più lingue. Inception ha 42 video in 9 lingue. amodb li restituisce tutti in una sola risposta. I parametri language e include_video_language non hanno effetto sugli endpoint dei video, quindi scegli la lingua nel tuo codice.

All'interno di ogni passaggio ordina per tipo e per flag official come nell'esempio. Le lingue dei video seguono il caricamento e non le 14 lingue dell'interfaccia elencate nella pagina lingue, quindi un trailer può essere cs o he.

Trailer per le serie

Il trailer di una serie sta in /3/tv/1396/videos (Breaking Bad), che contiene 9 trailer. La funzione di ordinamento qui sopra funziona così com'è, perché i campi non cambiano. I percorsi di stagioni ed episodi come /3/tv/1396/season/1/videos rispondono 200 con una lista results vuota, quindi leggi la lista della serie. Vedi video e trailer per l'elenco completo dei percorsi.

Costruire un carosello di trailer

Un carosello di film in sala richiede una chiamata di lista e una chiamata per titolo: GET /3/movie/now_playing (vedi tendenze e liste) più dieci chiamate di video fanno 11 richieste per dieci titoli. Salva la key scelta accanto all'ID del film. I trailer cambiano di rado, quindi aggiorna una scelta salvata ogni poche ore o quando un titolo torna in sala.

Confronto

Prezzi

I piani sono prepagati. Acquisti 1, 3, 6, 12 o 24 mesi e ottieni uno sconto di 0, 10, 20, 30 o 40 per cento per i periodi più lunghi. Nulla si rinnova da solo. I piani da 20, 40 e 120 richieste al minuto servono tutti ogni endpoint di questa pagina, quindi un carosello di trailer molto usato è solo una questione di frequenza. Non esistono un piano gratuito né una prova. Confronta i piani nella pagina dei prezzi.