# Многоезично 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/bg/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/bg/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/bg/translations/). Едно извикване за преводи замества до 14 извиквания за детайли, когато искате всички езици наведнъж.

## Постери и видеа по език

Снимките и видеата носят собствени тагове за език в `iso_639_1`. На ендпойнтите за изображения подайте списък, разделен със запетая, и добавете `null` за елементи без език, например постери без текст. Отговорът съдържа съвпадащите елементи, така че подредете ги във вашия код.

| Параметър                | Къде се ползва           | Пример       |
| ------------------------ | ------------------------ | ------------ |
| `include_image_language` | Ендпойнти за изображения | `ru,en,null` |

Ендпойнтите за видеа връщат всички езици в един отговор и игнорират `include_video_language`, затова филтрирайте по `iso_639_1` сами. Вижте [изображения](https://amodb.dev/bg/images-api/) за размерите и CDN.

## Иврит и текст отдясно наляво

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

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