API de trailers de filmes

Obtenha o trailer oficial de um filme

GET /3/movie/{movie_id}/videos retorna todos os vídeos ligados a um filme. Cada item tem um type, uma flag official, um código de idioma, um timestamp published_at e o site e a key que identificam o vídeo. Mantenha os itens em que type é Trailer e official é true, e você tem o seu trailer.

Você recebe uma lista de registros de vídeo que pode classificar por conta própria, não um stream. A resposta nomeia o vídeo e diz onde ele está, e sua página monta o player a partir de site e key. O mesmo formato volta para séries de TV. Os caminhos de temporada e episódio respondem com uma lista vazia.

Quais dados você recebe

Campos de cada vídeo:

Comece em 3 passos

1. Escolha um plano em preços. Todo plano retorna todos os dados, então você escolhe pelas requisições por minuto.
2. Crie uma chave no painel da sua conta. Ela tem 32 caracteres hexadecimais em minúsculas.
3. Chame GET /3/movie/{movie_id}/videos com a chave em api_key ou em um header Authorization: Bearer.

Exemplo de requisição

O exemplo pede os vídeos de Inception (id 27205), classifica-os no código e imprime o melhor. A classificação coloca primeiro as correspondências de idioma, depois Trailer antes de Teaser, depois oficial antes de não oficial e por fim o published_at mais 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');

Resposta reduzida: os 2 primeiros de 42 vídeos. A lista contém todos os idiomas.

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

Escolha qual vídeo reproduzir

Um título costuma ter vários trailers oficiais (um primeiro anúncio, um corte final) ao lado de teasers e clipes. Classifique-os com uma ordem fixa para que a página nunca coloque um vídeo de erros de gravação no espaço do trailer.

Desempate por published_at. O mais novo primeiro dá o corte mais recente, e o mais antigo primeiro dá o primeiro anúncio.

Idiomas dos trailers

Os vídeos recebem uma marca de idioma em iso_639_1, e um título pode ter trailers em vários. Inception tem 42 vídeos em 9 idiomas. O amodb retorna todos eles em uma só resposta. Os parâmetros language e include_video_language não têm efeito nos endpoints de vídeos, então escolha o idioma no seu código.

Classifique dentro de cada passo por tipo e pela flag official, como no exemplo. Os idiomas dos vídeos seguem o upload, não os 14 idiomas da interface listados em idiomas, então um trailer pode ser cs ou he.

Trailers de séries

O trailer de uma série fica em /3/tv/1396/videos (Breaking Bad), que tem 9 trailers. A função de classificação acima funciona como está, porque os campos não mudam. Caminhos de temporada e episódio como /3/tv/1396/season/1/videos respondem 200 com uma lista results vazia, então leia a lista da série. Veja vídeos e trailers para a lista completa de caminhos.

Monte uma fileira de trailers

Uma fileira de filmes em cartaz precisa de uma chamada de lista e uma chamada por título: GET /3/movie/now_playing (veja em alta e listas) mais dez chamadas de vídeos dão 11 requisições para dez títulos. Guarde a key escolhida junto ao id do filme. Os trailers mudam pouco, então atualize uma escolha guardada a cada poucas horas ou quando um título for relançado.

Como se compara

Preços

Os planos são pré-pagos. Você compra 1, 3, 6, 12 ou 24 meses e ganha 0, 10, 20, 30 ou 40 por cento de desconto nos períodos mais longos. Nada renova sozinho. Os planos de 20, 40 e 120 requisições por minuto atendem todos os endpoints desta página, então uma fileira de trailers movimentada é só uma questão de taxa. Não há plano gratuito nem período de teste. Compare os planos em preços.