# API багатомовних метаданих фільмів

> Це API багатомовних метаданих фільмів віддає назви, описи, слогани, назви жанрів і біографії 14 мовами на одному ключі: англійською, російською, українською, білоруською, китайською, португальською, болгарською, івритом, чеською, румунською, французькою, польською, італійською та іспанською. Передайте тег TMDB, наприклад ru-RU, у параметрі language.

## Отримайте дані фільму 14 мовами

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

Ви отримуєте 14 мов на одному ключі, `original_title` кожного фільму, ендпоінт перекладів, що перелічує всі мови тайтла, і локалізовані назви жанрів. Повний список наведено на сторінці [мови](https://amodb.dev/uk/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/uk/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/uk/translations/). Один виклик перекладів замінює до 14 викликів деталей, коли потрібні всі мови одразу.

## Постери й відео за мовою

Зображення й відео мають власні мовні теги в `iso_639_1`. На ендпоінтах зображень передайте список через кому й додайте `null` для елементів без мови, як-от постери без тексту. Відповідь містить відповідні елементи, тож ранжуйте їх у своєму коді.

| Параметр                 | Де використовується | Приклад      |
| ------------------------ | ------------------- | ------------ |
| `include_image_language` | Ендпоінти зображень | `ru,en,null` |

Ендпоінти відео повертають усі мови в одній відповіді та ігнорують `include_video_language`, тож фільтруйте за `iso_639_1` самостійно. Розміри та CDN дивіться в розділі [API зображень](https://amodb.dev/uk/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 запитів на хвилину включають усі мови й усі ендпоінти. Сайту п'ятьма мовами потрібно до п'яти викликів деталей на тайтл, а повторні запити віддаються з edge-кешу протягом 6 годин. Безкоштовного тарифу немає. Дивіться [ціни](https://amodb.dev/uk/pricing/).

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

### Якими мовами працює API?

14 мовами: англійською, російською, українською, білоруською, китайською, португальською, болгарською, івритом, чеською, румунською, французькою, польською, італійською та іспанською, з кодами 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. Серіали й серії мають той самий ендпоінт, де замість title використовується name. Сезони, персони та колекції перекладів не мають.

### Як обробити відсутній опис обраною мовою?

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

### Чи локалізовані також постери?

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

## Пов'язані сторінки

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

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