# 多语言电影元数据 API

> 这个多语言电影元数据 API 以 14 种语言提供片名、简介、宣传语、类型名和人物传记，涵盖英语、俄语、乌克兰语、中文、希伯来语等。在 language 参数中传入 ru-RU 这样的 TMDB 标签即可。

## 获取 14 种语言的电影数据

`GET /3/movie/{movie_id}?language=ru-RU` 以俄语返回片名、简介、宣传语和类型名。`language` 参数接受 `ru-RU` 或 `pt-BR` 这样的 TMDB 标签，适用于所有返回文本的接口。各语言的 ID 保持不变，因此数据库中的一行就能服务所有语言。

你用一个密钥得到 14 种语言、每部电影的 `original_title`、列出一部作品所有语言的译文接口，以及本地化的类型名。完整列表见[语言](https://amodb.dev/zh/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` 标记的视频，所有语言都在一个响应中        |

## 三步开始

1. 在[定价](https://amodb.dev/zh/pricing/)页选择套餐。语言数量不随套餐变化，变化的只有请求速率。
2. 在账户后台创建密钥。
3. 带上 `language` 标签调用任意接口，密钥以 `api_key` 或 Bearer 请求头发送。

## 请求示例

bash 示例用三种语言打印《搏击俱乐部》（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` 的响应，只保留了几个字段。PHP 示例中的键 `text_language` 是你的代码添加的，不是 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. 记录每个字段来自哪种语言，以便以后重试。

边缘缓存为每个已缓存的路径保存每种语言各一份，所以热门作品的英文回退通常直接来自缓存。

## 列出一部作品的所有译文

`GET /3/movie/{movie_id}/translations` 返回一个 `translations` 数组，为每种有数据的语言提供一项。列表可能比提供的 14 种语言更长：《搏击俱乐部》有 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/zh/translations/)。当你想一次获得所有语言时，一次译文调用可取代最多 14 次详情调用。

## 按语言获取海报和视频

图片和视频在 `iso_639_1` 中带有各自的语言标签。在图片接口上，传入逗号分隔的列表，并为没有语言的项目（例如不含文字的海报）加上 `null`。响应包含匹配的项目，所以请在代码中对它们排序。

| 参数                       | 用于   | 示例           |
| ------------------------ | ---- | ------------ |
| `include_image_language` | 图片接口 | `ru,en,null` |

视频接口会在一个响应中返回所有语言，并忽略 `include_video_language`，所以请自己按 `iso_639_1` 过滤。尺寸和 CDN 见[图片](https://amodb.dev/zh/images-api/)。

## 希伯来语与从右到左的文本

希伯来语是这 14 种语言中唯一从右到左的语言。请在页面中处理，而不是在数据中处理：

- 在容纳文本的元素上设置 `lang="he"` 和 `dir="rtl"`。
- 把希伯来语文本中的拉丁字母片名包在 `<bdi>` 元素里，避免标点跳到错误的一侧。
- 使用 `margin-inline-start` 这类逻辑 CSS 属性，而不是 left 和 right。

## 对比

| 能力        | 自己抓取页面         | 仅英文数据集 | amodb                            |
| --------- | -------------- | ------ | -------------------------------- |
| 语言        | 每个请求一个站点区域设置   | 英语     | 通过 `language` 支持 14 种语言          |
| 跨语言的同一 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 小时。没有免费额度。见[定价](https://amodb.dev/zh/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。电视剧和单集有同样的接口，用 name 代替 title。季、人物和系列合集没有译文。

### 所选语言缺少简介时怎么办？

先检查空字符串，然后用 en-US 再请求同一个 ID，或从译文列表中读取英文条目。最后用 original_title 兜底，并把该文本标记为英文。片名和宣传语本身也可能直接以英文返回。

### 海报也本地化了吗？

海报带有语言标签。用 include_image_language 请求，例如 ru,en,null，并在代码中对匹配项排序。图片文件来自 img.amodb.dev，无需密钥。

## 相关页面

- [语言](https://amodb.dev/zh/languages/): amodb 以 14 种语言提供片名、简介和姓名。在 language 中传入 ru-RU 或 pt-BR 这样的 TMDB 风格标签，其他标签回退到英语。
- [翻译 API](https://amodb.dev/zh/translations/): 兼容 TMDB v3 路径的翻译 API：一次读取电影、剧集或单集以所有语言存储的标题、简介和宣传语，无需逐个语言请求。
- [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。
- [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 ID 获取剧集的季、电视网和下一集，以及内容分级和观看平台。
- [图片 API 与图片主机](https://amodb.dev/zh/images-api/): 采用 TMDB v3 路径的电影图片 API：列出作品的海报、背景图、标志和剧照，再从 img.amodb.dev 以 10 种尺寸无密钥加载。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/multilingual-movie-metadata-api/