# Многоязычный API метаданных фильмов

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

## Данные о фильмах на 14 языках

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

Вы получаете 14 языков на одном ключе, `original_title` каждого фильма, эндпоинт переводов со всеми языками тайтла и локализованные названия жанров. Полный список приведен на странице [языки](https://amodb.dev/ru/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/ru/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. Если поле пустое, запросите тот же ID с `en-US` или возьмите английскую запись из списка переводов.
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/ru/translations/). Один запрос переводов заменяет до 14 запросов деталей, когда нужны сразу все языки.

## Постеры и видео по языку

Изображения и видео несут собственные языковые теги в `iso_639_1`. На эндпоинтах изображений передайте список через запятую и добавьте `null` для элементов без языка, например постеров без текста. Ответ содержит подходящие элементы, поэтому ранжируйте их в своем коде.

| Параметр                 | Где используется      | Пример       |
| ------------------------ | --------------------- | ------------ |
| `include_image_language` | Эндпоинты изображений | `ru,en,null` |

Эндпоинты видео возвращают все языки в одном ответе и игнорируют `include_video_language`, поэтому фильтруйте по `iso_639_1` самостоятельно. Размеры и CDN описаны на странице [API изображений](https://amodb.dev/ru/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/ru/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. У сериалов и серий такой же эндпоинт, только вместо title используется name. У сезонов, людей и коллекций переводов нет.

### Что делать, если описание на выбранном языке отсутствует?

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

### Локализованы ли постеры?

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

## Связанные страницы

- [Языки](https://amodb.dev/ru/languages/): amodb отдает названия, описания и имена на 14 языках. Передайте в language тег в стиле TMDB, например ru-RU или pt-BR; другие теги откатываются на английский.
- [API переводов](https://amodb.dev/ru/translations/): API переводов фильмов с путями TMDB v3: читайте все сохраненные названия, описания и слоганы фильма, сериала или серии сразу на всех языках.
- [API деталей фильма](https://amodb.dev/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках.
- [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра.
- [API изображений и хост изображений](https://amodb.dev/ru/images-api/): API изображений фильмов с путями TMDB v3: списки постеров, фонов, логотипов и кадров для каждого проекта, загрузка с img.amodb.dev в 10 размерах без ключа.
- [Быстрый старт](https://amodb.dev/ru/quickstart/): Первый вызов amodb: получите ключ, запросите детали фильма через curl, JavaScript, Python, PHP или Go и загрузите постер с img.amodb.dev. Меньше 2 минут.

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