Movie trailer API

Get the official trailer for a movie

GET /3/movie/{movie_id}/videos returns every video attached to a movie. Each item has a type, an official flag, a language code, a published_at timestamp, and the site and key that identify the video. Keep the items where type is Trailer and official is true, and you have your trailer.

You get a list of video records you can rank yourself, not a stream. The reply names the video and where it lives, and your page builds the player from site and key. The same shape comes back for TV series. Season and episode paths answer with an empty list.

What data you get

Fields on every video:

Start in 3 steps

1. Choose a plan on pricing. Every plan returns all data, so you pick by requests per minute.
2. Create a key in your account dashboard. It is 32 lowercase hex characters.
3. Call GET /3/movie/{movie_id}/videos with the key in api_key or in an Authorization: Bearer header.

Example request

The sample asks for the videos of Inception (id 27205), ranks them in code, and prints the best one. Ranking puts language matches first, then Trailer before Teaser, then official before unofficial, then the newest 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');

Trimmed response: the first 2 of 42 videos. The list holds all languages.

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

Choose which video to play

A title often has several official trailers (a first announcement, a final cut) next to teasers and clips. Rank them with a fixed order so the page never ends up with a blooper reel in the trailer slot.

Sort ties by published_at. Newest first gives the latest cut, oldest first gives the first announcement.

Trailer languages

Videos are tagged with a language through iso_639_1, and one title can have trailers in several. Inception has 42 videos in 9 languages. amodb returns all of them in one reply. The language and include_video_language parameters have no effect on the videos endpoints, so choose the language in your code.

Rank inside each step by type and the official flag as in the sample. Video languages follow the upload, not the 14 interface languages listed on languages, so a trailer can be cs or he.

Trailers for series

A series trailer lives at /3/tv/1396/videos (Breaking Bad), which holds 9 trailers. The ranking function above works as is, because the fields do not change. Season and episode paths such as /3/tv/1396/season/1/videos answer 200 with an empty results list, so read the series list instead. See videos and trailers for the full path list.

Build a trailer rail

A rail of now playing movies needs one list call and one call per title: GET /3/movie/now_playing (see trending and lists) plus ten video calls make 11 requests for ten titles. Store the picked key next to the movie id. Trailers change rarely, so refresh a stored pick every few hours or when a title is re-released.

How it compares

Pricing

Plans are prepaid. You buy 1, 3, 6, 12 or 24 months and get 0, 10, 20, 30 or 40 percent off for the longer periods. Nothing renews by itself. The 20, 40 and 120 requests per minute plans all serve every endpoint on this page, so a busy trailer rail is a question of rate only. There is no free tier and no trial. Compare plans on pricing.