# Шматмоўнае API метаданых фільмаў

> Гэта шматмоўнае API метаданых фільмаў аддае назвы, апісанні, слоганы, назвы жанраў і біяграфіі на 14 мовах: англійскай, рускай, украінскай, беларускай, кітайскай, партугальскай, балгарскай, іўрыце, чэшскай, румынскай, французскай, польскай, італьянскай і іспанскай. Перадайце ў параметр language тэг TMDB, напрыклад ru-RU, і атрымайце тэкст на гэтай мове.

## Атрыманне даных фільма на 14 мовах

`GET /3/movie/{movie_id}?language=ru-RU` вяртае назву, апісанне, слоган і назвы жанраў па-руску. Параметр `language` прымае тэгі TMDB, напрыклад `ru-RU` або `pt-BR`, і працуе на кожным эндпоінце, што вяртае тэкст. Id застаюцца тымі ж на кожнай мове, таму адзін радок у вашай базе даных абслугоўвае ўсе мовы.

Вы атрымліваеце 14 моў на адным ключы, `original_title` кожнага фільма, эндпоінт перакладаў са спісам усіх моў назвы і лакалізаваныя назвы жанраў. Поўны спіс ёсць на старонцы [мовы](https://amodb.dev/be/languages/).

## 14 падтрымліваных моў

| Мова          | Код  | Прыклад тэга |
| ------------- | ---- | ------------ |
| Англійская    | `en` | `en-US`      |
| Руская        | `ru` | `ru-RU`      |
| Украінская    | `uk` | `uk-UA`      |
| Беларуская    | `be` | `be-BY`      |
| Кітайская     | `zh` | `zh-CN`      |
| Партугальская | `pt` | `pt-BR`      |
| Балгарская    | `bg` | `bg-BG`      |
| Іўрыт         | `he` | `he-IL`      |
| Чэшская       | `cs` | `cs-CZ`      |
| Румынская     | `ro` | `ro-RO`      |
| Французская   | `fr` | `fr-FR`      |
| Польская      | `pl` | `pl-PL`      |
| Італьянская   | `it` | `it-IT`      |
| Іспанская     | `es` | `es-ES`      |

Любы іншы тэг замяняецца на `en`. Японская і карэйская не падтрымліваюцца як мовы інтэрфейсу. Іх арыгінальныя назвы ўсё роўна вяртаюцца ў `original_title` для фільмаў і `original_name` для серыялаў.

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

| Эндпоінт                                   | Лакалізаваны змест                                                 |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, назвы жанраў                       |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, назвы жанраў                        |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` і `overview` сезона і эпізодаў                              |
| `GET /3/person/{person_id}`                | `biography`                                                        |
| `GET /3/genre/movie/list`                  | Назвы жанраў для фільтраў і меню                                   |
| `GET /3/movie/{movie_id}/translations`     | Усе мовы назвы ў адным адказе                                      |
| `GET /3/movie/{movie_id}/images`           | Постэры з пазнакай мовы, фільтруюцца праз `include_image_language` |
| `GET /3/movie/{movie_id}/videos`           | Відэа з пазнакай `iso_639_1`, усе мовы ў адным адказе              |

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

1. Абярыце план на старонцы [цэны](https://amodb.dev/be/pricing/). Колькасць моў не залежыць ад плана, залежыць толькі частата запытаў.
2. Стварыце ключ у асабістым кабінеце.
3. Выклічце любы эндпоінт з тэгам `language` і перадайце ключ як `api_key` або ў загалоўку Bearer.

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

Прыклад на bash друкуе назву Fight Club (id `550`) на трох мовах. Ён выкарыстоўвае `jq`, каб надрукаваць адно поле. Прыклад на PHP запытвае беларускую і пераключаецца на англійскую, калі апісанне пустое.

```bash
for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done
```

```php
<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        throw new RuntimeException("amodb returned $status");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;
```

Адказ для `language=ru-RU`, скарочаны да некалькіх палёў. Ключ `text_language` у прыкладзе на PHP дадае ваш код, а не API.

```json
{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}
```

## Запасны варыянт, калі поле пустое

Не ў кожнай назвы ёсць тэкст на кожнай мове. `overview` можа вярнуцца пустым, калі перакладу няма, а `title` або `tagline` могуць вярнуцца па-англійску. API не прыдумляе тэкст. Выкарыстоўвайце фіксаваны парадак, каб старонка заўсёды штосьці паказвала:

1. Запытайце мову, якую паказваеце.
2. Калі поле пустое, запытайце `en-US` для таго ж id або прачытайце англійскі запіс са спісу перакладаў.
3. Калі назва пустая, паказвайце `original_title`.
4. Захоўвайце, з якой мовы ўзята кожнае поле, каб потым паўтарыць спробу.

Edge-кэш трымае адну копію на мову для кожнага кэшаванага шляху, таму англійскі запасны варыянт для папулярнай назвы звычайна аддаецца з кэшу.

## Спіс усіх перакладаў назвы

`GET /3/movie/{movie_id}/translations` вяртае масіў `translations`, па запісе на кожную мову, дзе ёсць даныя. Спіс можа быць даўжэйшы за 14 падтрымліваных моў: у Fight Club 50 запісаў. Выкарыстоўвайце яго, каб пабудаваць пераключальнік моў або захаваць усе тэксты назвы ў адным радку.

| Поле                                                                             | Сэнс                                        |
| -------------------------------------------------------------------------------- | ------------------------------------------- |
| `iso_639_1`, `iso_3166_1`                                                        | Коды мовы і краіны                          |
| `english_name`                                                                   | Назва мовы па-англійску                     |
| `data.title` (фільмы) або `data.name` (серыялы), `data.overview`, `data.tagline` | Лакалізаваны тэкст, назва можа быць пустой  |
| `data.homepage`, `data.runtime`                                                  | Неабавязковыя значэнні для гэтага перакладу |

Той жа эндпоінт ёсць для серыялаў і эпізодаў. Запісы серыялаў нясуць `data.name` і не маюць `runtime`, а запісы эпізодаў нясуць толькі `name` і `overview`. Сезоны адказваюць пустым спісам, а ў персон і калекцый эндпоінта перакладаў няма. Падрабязнасці на старонцы [пераклады](https://amodb.dev/be/translations/). Адзін выклік перакладаў замяняе да 14 выклікаў дэталяў, калі патрэбны ўсе мовы адразу.

## Постэры і відэа па мовах

Выявы і відэа маюць свае тэгі мовы ў `iso_639_1`. На эндпоінтах выяў перадайце спіс праз коску і дадайце `null` для элементаў без мовы, напрыклад постэраў без тэксту. Адказ утрымлівае адпаведныя элементы, таму ранжыруйце іх у сваім кодзе.

| Параметр                 | Дзе выкарыстоўваецца | Прыклад      |
| ------------------------ | -------------------- | ------------ |
| `include_image_language` | Эндпоінты выяў       | `ru,en,null` |

Эндпоінты відэа вяртаюць усе мовы ў адным адказе і ігнаруюць `include_video_language`, таму фільтруйце па `iso_639_1` самі. Памеры і CDN гл. на старонцы [выявы](https://amodb.dev/be/images-api/).

## Іўрыт і тэкст справа налева

Іўрыт гэта адзіная мова з 14, якая пішацца справа налева. Апрацоўвайце яго на старонцы, а не ў даных:

- Задайце `lang="he"` і `dir="rtl"` на элеменце з тэкстам.
- Загарніце лацінскія назвы ўнутры іўрыцкага тэксту ў элемент `<bdi>`, каб знакі прыпынку не пераскоквалі на няправільны бок.
- Выкарыстоўвайце лагічныя ўласцівасці CSS, напрыклад `margin-inline-start`, замест left і right.

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

| Магчымасць              | Уласны скрэйпінг старонак          | Набор даных толькі па-англійску | amodb                             |
| ----------------------- | ---------------------------------- | ------------------------------- | --------------------------------- |
| Мовы                    | Адна лакаль сайта на запыт         | Англійская                      | 14 моў праз `language`            |
| Той жа id на ўсіх мовах | Розныя URL для кожнай лакалі       | Не ўжываецца                    | Той жа лікавы id усюды            |
| Усе пераклады назвы     | Спампоўваць старонку кожнай лакалі | Не ўжываецца                    | Адзін выклік `translations`       |
| Лакалізаваныя постэры   | URL выяў для кожнай лакалі         | Глядзіце іх дакументацыю        | Фільтр `include_image_language`   |
| Арыгінальная назва      | Разбіраць з тэксту старонкі        | Глядзіце іх дакументацыю        | `original_title`, `original_name` |

## Цэны

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

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

### Якія мовы падтрымлівае API?

Чатырнаццаць: англійская, руская, украінская, беларуская, кітайская, партугальская, балгарская, іўрыт, чэшская, румынская, французская, польская, італьянская і іспанская, з кодамі en ru uk be zh pt bg he cs ro fr pl it es.

### Што адбываецца, калі я адпраўлю тэг мовы, якая не падтрымліваецца?

Адказ замяняецца англійскім. Тэг, напрыклад ja-JP, вяртае англійскі тэкст, а арыгінальная японская назва ўсё роўна прыходзіць у original_title для фільмаў і original_name для серыялаў.

### Ці можна атрымаць усе пераклады назвы адным запытам?

Так. GET /3/movie/{movie_id}/translations пералічвае па запісе на кожную мову, дзе ёсць даныя, кожны з title, overview, tagline, homepage і runtime. У серыялаў і эпізодаў той жа эндпоінт, з name замест title. У сезонаў, персон і калекцый перакладаў няма.

### Як апрацаваць адсутнае апісанне на абранай мове?

Праверце пусты радок, потым зноў запытайце той жа id з en-US або прачытайце англійскі запіс са спісу перакладаў. Як апошні запасны варыянт паказвайце original_title і пазначайце тэкст як англійскі. Назвы і слоганы таксама могуць ужо вяртацца па-англійску.

### Ці лакалізаваныя таксама постэры?

Постэры маюць тэг мовы. Запытвайце іх праз include_image_language, напрыклад ru,en,null, і ранжыруйце супадзенні ў сваім кодзе. Файлы выяў прыходзяць з img.amodb.dev і не патрабуюць ключа.

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

- [Мовы](https://amodb.dev/be/languages/): amodb аддае назвы, апісанні і імёны на 14 мовах. Перадайце тэг у стылі TMDB, напрыклад ru-RU або pt-BR, у language; любы іншы тэг замяняецца англійскай мовай.
- [API перакладаў](https://amodb.dev/be/translations/): 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 з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду.
- [API выяў і хост выяў](https://amodb.dev/be/images-api/): API выяў фільмаў з шляхамі TMDB v3: спісы постэраў, фонавых выяў, лагатыпаў і кадраў назвы, а потым загрузка з img.amodb.dev у 10 памерах без ключа.
- [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны.

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