# API трейлерів фільмів

> API трейлерів фільмів це GET /3/movie/{movie_id}/videos на api.amodb.dev. Кожне відео має тип, прапорець official, мову та дату публікації, тож офіційний трейлер можна вибрати за один прохід по списку. Серіали повертають ту саму структуру, а шляхи й 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/uk/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/uk/languages/), тож трейлер може бути `cs` або `he`.

## Трейлери для серіалів

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

## Складіть стрічку трейлерів

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

## Порівняння

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

## Ціни

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

## Запитання й відповіді

### Як отримати офіційний трейлер фільму?

Викличте GET /3/movie/{movie_id}/videos, залиште елементи, де type дорівнює Trailer, а official дорівнює true, потім відсортуйте за published_at. Перший елемент це найновіший офіційний трейлер. Якщо трейлера немає, використайте Teaser.

### Чи повертає API відеофайл або потік?

Ні. Він повертає метадані кожного відео: name, type, site, key, size, language і дати. Посилання на програвач ви будуєте з site і key або вбудовуєте відео на власній сторінці. Постери й кадри беруться з img.amodb.dev.

### Як отримати трейлери своєю мовою?

Ендпоінт videos повертає всі мови в одній відповіді та ігнорує параметри 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/uk/videos-trailers/): API відео фільмів зі шляхами TMDB v3: список трейлерів, тизерів, кліпів і фічерет для фільму чи серіалу з фільтрацією за типом і мовою у вашому коді.
- [API деталей фільму](https://amodb.dev/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами.
- [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги.
- [Ендпоінти трендів і списків](https://amodb.dev/uk/trending-lists/): API трендів фільмів зі шляхами TMDB v3: чарти за день і тиждень, а також списки в прокаті, популярних, найкращих і майбутніх фільмів та серіалів, кеш 30 хвилин.
- [Мови](https://amodb.dev/uk/languages/): amodb віддає назви, описи та імена 14 мовами. Передайте в language тег у стилі TMDB, наприклад ru-RU або pt-BR; будь-який інший тег переходить на англійську.
- [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини.

Оновлено: 2026-10-18. Source: https://amodb.dev/uk/movie-trailer-api/