# 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`                                           | Трейлъри, тийзъри, клипове, featurette, зад кулисите и гафове за филм |
| `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/bg/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/bg/languages/), така че трейлърът може да е `cs` или `he`.

## Трейлъри за сериали

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

## Изграждане на лента с трейлъри

Лента с филми, които вървят в момента, иска едно извикване за списък и по едно извикване на заглавие: `GET /3/movie/now_playing` (вижте [тенденции и списъци](https://amodb.dev/bg/trending-lists/)) плюс десет извиквания за видеа правят 11 заявки за десет заглавия. Пазете избрания `key` до id на филма. Трейлърите се променят рядко, така че обновявайте запазения избор на няколко часа или когато заглавието излезе отново.

## Как се сравнява

| Възможност          | Сами да обработвате страници           | API за метаданни с безплатен план | amodb                                                                   |
| ------------------- | -------------------------------------- | --------------------------------- | ----------------------------------------------------------------------- |
| Флаг за официалност | Налучкване по заглавието на страницата | Вижте документацията им           | Булево `official` при всяко видео                                       |
| Филтър по тип видео | Разчитане на текст                     | Вижте документацията им           | Шест стойности на `type`                                                |
| Избор на език       | Една локализация на страница           | Вижте документацията им           | `iso_639_1` и `iso_3166_1` при всяко видео, филтрират се във вашия код  |
| Сериали и епизоди   | Отделни страници за обхождане          | Вижте документацията им           | Сериалите ползват същия ендпойнт, списъците за сезон и епизод са празни |
| Поддръжка           | Чупи се, когато се промени разметката  | Зависи от доставчика              | Една стабилна форма на JSON                                             |
| Условия             | Рискът е ваш                           | Вижте техните условия             | Платени планове, вижте [цени](https://amodb.dev/bg/pricing/)            |

## Цени

Плановете са предплатени. Купувате 1, 3, 6, 12 или 24 месеца и получавате отстъпка 0, 10, 20, 30 или 40 процента за по-дългите периоди. Нищо не се подновява само. Плановете за 20, 40 и 120 заявки в минута обслужват всеки ендпойнт на тази страница, така че натоварена лента с трейлъри е въпрос само на скорост. Няма безплатен план и пробен период. Сравнете плановете на страницата с [цените](https://amodb.dev/bg/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/bg/videos-trailers/): API за видеа с пътища на TMDB v3: списък с трейлъри, тийзъри, клипове и featurette за филм или сериал, после филтриране по тип и език във вашия код.
- [API за детайли на филм](https://amodb.dev/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика.
- [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане.
- [Ендпойнти за тенденции и списъци](https://amodb.dev/bg/trending-lists/): API за филми в тенденция с пътища на TMDB v3: класации за ден и седмица, списъци в кината, популярни, най-добри и предстоящи, кеш 30 минути.
- [Езици](https://amodb.dev/bg/languages/): amodb връща заглавия, описания и имена на 14 езика. Подайте таг в стил TMDB, например ru-RU или pt-BR, в language; всеки друг таг се заменя с английски.
- [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути.

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