# API трэйлераў фільмаў

> API трэйлераў фільмаў гэта GET /3/movie/{movie_id}/videos на api.amodb.dev. Кожнае відэа нясе тып, прыкмету афіцыйнасці, мову і дату публікацыі, таму афіцыйны трэйлер можна выбраць за адзін праход. Серыялы вяртаюць ту ж форму. Шляхі і JSON адпавядаюць TMDB v3, таму існуючыя кліенты працуюць без змен.

## Атрыманне афіцыйнага трэйлера фільма

`GET /3/movie/{movie_id}/videos` вяртае кожнае відэа, прывязанае да фільма. Кожны запіс мае `type`, прыкмету `official`, код мовы, часовую пазнаку `published_at`, а таксама `site` і `key`, якія ідэнтыфікуюць відэа. Пакіньце запісы, дзе `type` роўны `Trailer` і `official` роўны `true`, і трэйлер у вас у руках.

Вы атрымліваеце спіс запісаў відэа, якія можна ранжыраваць самім, а не струмень. Адказ называе відэа і месца, дзе яно жыве, а ваша старонка будуе прайгравальнік з `site` і `key`. Тая ж форма вяртаецца для серыялаў. Шляхі сезонаў і эпізодаў адказваюць пустым спісам.

## Якія даныя вы атрымліваеце

| Эндпоінт                                                                   | Што вяртае                                                                   |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}/videos`                                           | Трэйлеры, тызеры, кліпы, фічарэты, матэрыялы за кадрам і абляпухі для фільма |
| `GET /3/tv/{tv_id}/videos`                                                 | Той жа спіс для серыяла                                                      |
| `GET /3/tv/{tv_id}/season/{season_number}/videos`                          | Заўсёды пусты спіс `results`                                                 |
| `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | Заўсёды пусты спіс `results`                                                 |
| `GET /3/movie/{movie_id}` з `append_to_response=videos`                    | Дэталі і відэа адным запытам                                                 |

Палі кожнага відэа:

| Поле                      | Тып               | Прызначэнне                                                                                                    |
| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `type`                    | радок             | Від відэа: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` або `Bloopers`, як на старонцы відэа |
| `official`                | лагічнае значэнне | `true`, калі відэа пазначана як афіцыйнае                                                                      |
| `iso_639_1`, `iso_3166_1` | радок             | Коды мовы і краіны відэа                                                                                       |
| `key`, `site`             | радок             | Ідэнтыфікатар відэа і назва сайта, на якім яно размешчана, `YouTube` у кожнага відэа, якое мы бачылі           |
| `size`                    | цэлы лік          | Вертыкальнае разрозненне, `1080` у кожнага відэа, якое мы бачылі                                               |
| `published_at`            | радок             | Часовая пазнака ISO 8601, зручная для сартавання ад новых да старых                                            |
| `name`, `id`              | радок             | Назва відэа і яго id, які супадае са значэннем `key`                                                           |

## Пачніце за 3 крокі

1. Абярыце план на старонцы [цэны](https://amodb.dev/be/pricing/). Кожны план вяртае ўсе даныя, таму выбірайце па запытах у хвіліну.
2. Стварыце ключ у асабістым кабінеце. Гэта 32 малыя шаснаццатковыя сімвалы.
3. Выклічце `GET /3/movie/{movie_id}/videos` з ключом у `api_key` або ў загалоўку `Authorization: Bearer`.

## Прыклад запыту

У прыкладзе запытваюцца відэа Inception (id `27205`), ранжыруюцца ў кодзе, і друкуецца найлепшае. Ранжыраванне ставіць першымі супадзенні па мове, потым `Trailer` перад `Teaser`, потым афіцыйныя перад неафіцыйнымі, потым найноўшы `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');
```

Скарочаны адказ: першыя 2 з 42 відэа. Спіс змяшчае ўсе мовы.

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

## Як выбраць відэа для прайгравання

У назвы часта некалькі афіцыйных трэйлераў (першы анонс, фінальны мантаж) побач з тызерамі і кліпамі. Ранжыруйце іх у фіксаваным парадку, каб на месцы трэйлера ніколі не апынуліся абляпухі.

| Прыярытэт  | Фільтр                            | Тыповае выкарыстанне                                     |
| ---------- | --------------------------------- | -------------------------------------------------------- |
| 1          | `Trailer`, афіцыйны, мова супадае | Відэа для прайгравання                                   |
| 2          | `Trailer`, неафіцыйны             | Рэгіянальныя або фанацкія загрузкі, калі афіцыйнага няма |
| 3          | `Teaser`, афіцыйны                | Кароткія ролікі да выхаду                                |
| 4          | `Clip`, `Featurette`              | Запасны варыянт, каб месца не было пустым                |
| прапусціць | `Behind the Scenes`, `Bloopers`   | Паказваць у асобным спісе дадатковых матэрыялаў          |

Роўныя выпадкі сартуйце па `published_at`. Спачатку новыя даюць апошні мантаж, спачатку старыя даюць першы анонс.

## Мовы трэйлераў

Відэа пазначаюцца мовай праз `iso_639_1`, і ў адной назвы могуць быць трэйлеры на некалькіх мовах. У Inception 42 відэа на 9 мовах. amodb вяртае ўсе іх у адным адказе. Параметры `language` і `include_video_language` на эндпоінтах відэа не дзейнічаюць, таму мову выбірайце ў сваім кодзе.

| Крок | Што рабіць                                                                  |
| ---- | --------------------------------------------------------------------------- |
| 1    | Пакіньце відэа, у якіх `iso_639_1` супадае з карыстальнікам, напрыклад `ru` |
| 2    | Калі нічога не супала, пакіньце `en`                                        |
| 3    | Калі нічога не супала, пакіньце астатнія                                    |

Усярэдзіне кожнага кроку ранжыруйце па тыпе і прыкмеце `official`, як у прыкладзе. Мовы відэа залежаць ад загрузкі, а не ад 14 моў інтэрфейсу са старонкі [мовы](https://amodb.dev/be/languages/), таму трэйлер можа быць `cs` або `he`.

## Трэйлеры для серыялаў

Трэйлер серыяла знаходзіцца па `/3/tv/1396/videos` (Breaking Bad), дзе 9 трэйлераў. Функцыя ранжыравання вышэй працуе як ёсць, бо палі не мяняюцца. Шляхі сезонаў і эпізодаў, напрыклад `/3/tv/1396/season/1/videos`, адказваюць 200 з пустым спісам `results`, таму чытайце спіс серыяла. Поўны спіс шляхоў гл. на старонцы [відэа і трэйлеры](https://amodb.dev/be/videos-trailers/).

## Стужка трэйлераў

Стужка фільмаў, што зараз у пракаце, патрабуе аднаго выкліку спісу і па адным выкліку на назву: `GET /3/movie/now_playing` (гл. [трэнды і спісы](https://amodb.dev/be/trending-lists/)) плюс дзесяць выклікаў відэа дае 11 запытаў на дзесяць назваў. Захоўвайце выбраны `key` побач з id фільма. Трэйлеры мяняюцца рэдка, таму абнаўляйце захаваны выбар раз у некалькі гадзін або пры паўторным выхадзе назвы.

## Параўнанне

| Магчымасць           | Уласны скрэйпінг старонак         | API метаданых з бясплатным тарыфам | amodb                                                                    |
| -------------------- | --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------ |
| Прыкмета афіцыйнасці | Здагадвацца па загалоўку старонкі | Глядзіце іх дакументацыю           | Лагічнае `official` у кожным відэа                                       |
| Фільтр па тыпе відэа | Разбіраць тэкст                   | Глядзіце іх дакументацыю           | Шэсць значэнняў `type`                                                   |
| Выбар мовы           | Адна лакаль на старонку           | Глядзіце іх дакументацыю           | `iso_639_1` і `iso_3166_1` у кожным відэа, фільтруюцца ў вашым кодзе     |
| Серыялы і эпізоды    | Асобныя старонкі для абыходу      | Глядзіце іх дакументацыю           | Серыялы выкарыстоўваюць той жа эндпоінт, спісы сезонаў і эпізодаў пустыя |
| Падтрымка            | Ламаецца, калі змяняецца разметка | Залежыць ад пастаўшчыка            | Адна стабільная форма JSON                                               |
| Умовы                | Рызыку нясяце вы                  | Глядзіце іх умовы                  | Платныя планы, гл. [цэны](https://amodb.dev/be/pricing/)                 |

## Цэны

Планы аплачваюцца наперад. Вы купляеце 1, 3, 6, 12 або 24 месяцы і атрымліваеце зніжку 0, 10, 20, 30 або 40 працэнтаў за доўгія перыяды. Нічога не прадаўжаецца само. Планы на 20, 40 і 120 запытаў у хвіліну абслугоўваюць кожны эндпоінт на гэтай старонцы, таму загружаная стужка трэйлераў залежыць толькі ад частаты. Бясплатнага тарыфа і пробнага перыяду няма. Параўнайце планы на старонцы [цэны](https://amodb.dev/be/pricing/).

## Пытанні і адказы

### Як атрымаць афіцыйны трэйлер фільма?

Выклічце GET /3/movie/{movie_id}/videos, пакіньце запісы, дзе type роўны Trailer і official роўны true, потым адсартуйце па published_at. Першы запіс і ёсць найноўшы афіцыйны трэйлер. Калі трэйлера няма, звярніцеся да Teaser.

### Ці вяртае API відэафайл або струмень?

Не. Ён вяртае метаданыя кожнага відэа: name, type, site, key, size, мову і даты. Спасылку для прайгравальніка вы складаеце з site і key або ўбудоўваеце відэа на сваю старонку. Постэры і кадры бяруцца з img.amodb.dev.

### Як атрымаць трэйлеры на маёй мове?

Эндпоінт відэа вяртае ўсе мовы ў адным адказе і ігнаруе параметры language і include_video_language. Фільтруйце па iso_639_1 у сваім кодзе, напрыклад спачатку ru, потым en, потым астатнія. У Inception відэа на 9 мовах.

### Ці можна атрымаць трэйлеры для серыялаў і эпізодаў?

Для серыялаў так: выкарыстоўвайце /3/tv/{tv_id}/videos. Палі тыя ж, таму код ранжыравання, напісаны для фільмаў, працуе без змен. Шляхі відэа сезонаў і эпізодаў адказваюць пустым масівам results, таму карыстайцеся спісам серыяла.

### Колькі запытаў расходуе пошук трэйлера?

Адзін запыт на назву. З append_to_response=videos трэйлер прыходзіць у выкліку дэталяў, таму дэталі плюс трэйлер усё роўна ўяўляюць адзін запыт з вашых 20, 40 або 120 запытаў у хвіліну.

## Звязаныя старонкі

- [API відэа і трэйлераў](https://amodb.dev/be/videos-trailers/): API відэа з шляхамі TMDB v3: спіс трэйлераў, тызераў, кліпаў і фічарэтаў для фільма або серыяла, а потым фільтр па тыпе і мове ў вашым кодзе.
- [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах.
- [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду.
- [Эндпоінты трэндаў і спісаў](https://amodb.dev/be/trending-lists/): API трэндавых фільмаў з шляхамі TMDB v3: чарты за дзень і тыдзень, спісы зараз у пракаце, папулярных, лепшых і хутка ў пракаце, кэш 30 хвілін.
- [Мовы](https://amodb.dev/be/languages/): amodb аддае назвы, апісанні і імёны на 14 мовах. Перадайце тэг у стылі TMDB, напрыклад ru-RU або pt-BR, у language; любы іншы тэг замяняецца англійскай мовай.
- [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны.

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/movie-trailer-api/