# Movie trailer API > The movie trailer API is GET /3/movie/{movie_id}/videos on api.amodb.dev. Every video carries a type, an official flag, a language and a publish date, so you can pick the official trailer in one pass. Series return the same shape. Paths and JSON match TMDB v3. ## 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 | Endpoint | Returns | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/videos` | Trailers, teasers, clips, featurettes, behind the scenes and bloopers for a movie | | `GET /3/tv/{tv_id}/videos` | The same list for a series | | `GET /3/tv/{tv_id}/season/{season_number}/videos` | Always an empty `results` list | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | Always an empty `results` list | | `GET /3/movie/{movie_id}` with `append_to_response=videos` | Details and videos in one request | Fields on every video: | Field | Type | Use | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `type` | string | Kind of video: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` or `Bloopers`, as on the videos page | | `official` | boolean | `true` when the video is flagged as official | | `iso_639_1`, `iso_3166_1` | string | Language and country codes of the video | | `key`, `site` | string | Identifier of the video and the name of the site that hosts it, `YouTube` on every video seen | | `size` | integer | Vertical resolution, `1080` on every video seen | | `published_at` | string | ISO 8601 timestamp, good for newest-first sorting | | `name`, `id` | string | Title of the video and its id, which is the same string as `key` | ## Start in 3 steps 1. Choose a plan on [pricing](https://amodb.dev/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`. ```bash curl -s "https://api.amodb.dev/3/movie/27205/videos" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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. ```json { "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. | Priority | Filter | Typical use | | -------- | ------------------------------------- | ---------------------------------------------------- | | 1 | `Trailer`, official, language matches | The video to play | | 2 | `Trailer`, not official | Regional or fan uploads when nothing official exists | | 3 | `Teaser`, official | Short pre-release spots | | 4 | `Clip`, `Featurette` | Fallback so the slot is not empty | | skip | `Behind the Scenes`, `Bloopers` | Show in a separate extras list | 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. | Step | What to do | | ---- | --------------------------------------------------------------------- | | 1 | Keep the videos whose `iso_639_1` matches your user, for example `ru` | | 2 | If none match, keep `en` | | 3 | If none match, keep the rest | 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](https://amodb.dev/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](https://amodb.dev/videos-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](https://amodb.dev/trending-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 | Capability | Scrape pages yourself | Free-tier metadata API | amodb | | ------------------- | -------------------------- | ----------------------- | ------------------------------------------------------------------ | | Official flag | Guess from the page title | Check their docs | `official` boolean on every video | | Video type filter | Parse text | Check their docs | Six `type` values | | Language choice | One locale per page | Check their docs | `iso_639_1` and `iso_3166_1` on every video, filtered in your code | | Series and episodes | Separate pages to crawl | Check their docs | Series use the same endpoint, season and episode lists are empty | | Upkeep | Breaks when markup changes | Depends on the provider | One stable JSON shape | | Terms | You carry the risk | Check their terms | Paid plans, see [pricing](https://amodb.dev/pricing/) | ## 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](https://amodb.dev/pricing/). ## Questions and answers ### How do I get the official trailer of a movie? Call GET /3/movie/{movie_id}/videos, keep items where type is Trailer and official is true, then sort by published_at. The first item is the newest official trailer. If no trailer exists, fall back to a Teaser. ### Does the API return a video file or a stream? No. It returns metadata for each video: name, type, site, key, size, language and dates. You build the player link from site and key, or embed the video in your own page. Posters and stills come from img.amodb.dev. ### How do I get trailers in my language? The videos endpoint returns every language in one reply and ignores the language and include_video_language parameters. Filter on iso_639_1 in your code, for example ru first, then en, then the rest. Inception carries videos in 9 languages. ### Can I get trailers for TV series and episodes? For series, yes: use /3/tv/{tv_id}/videos. The fields are the same, so the ranking code you wrote for movies works unchanged. The season and episode video paths answer with an empty results array, so use the series list. ### How many requests does a trailer lookup use? One request per title. With append_to_response=videos the trailer arrives inside the details call, so details plus trailer is still one request against your 20, 40 or 120 requests per minute. ## Related pages - [Videos and trailers API](https://amodb.dev/videos-trailers/): Movie videos API with TMDB v3 paths: list trailers, teasers, clips and featurettes for a movie or series, then filter by type and language in your code. - [Movie details API](https://amodb.dev/movies/): Movie details API with the same paths and JSON as TMDB v3. Get one movie by id, add credits, ratings and moods with append_to_response, in 14 languages. - [TV series API, the TV show endpoint](https://amodb.dev/tv-series/): TV show API reference for GET /3/tv/{series_id}: names, status, seasons, networks and the next episode, in TMDB v3 JSON with content ratings and providers. - [Trending and list endpoints](https://amodb.dev/trending-lists/): Trending movies API with TMDB v3 paths: day and week charts, plus now playing, popular, top rated and upcoming lists for movies and TV, cached for 30 minutes. - [Languages](https://amodb.dev/languages/): amodb serves titles, overviews and names in 14 languages. Pass a TMDB style tag such as ru-RU or pt-BR in language; any other tag falls back to English. - [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes. Updated: 2026-10-18. Source: https://amodb.dev/movie-trailer-api/