# IMDb API 替代方案

> IMDb 没有免费的通用 REST API：其非商业数据集是可下载的文件，商业访问需要授权。amodb 是付费 JSON API，你可以按 IMDb ID 查找作品，读取已知的 IMDb 评分和投票数，并用同一个密钥获取演职员、图片和预告片。

## 通过 REST 获取 IMDb 数据：简短回答

IMDb 没有免费的通用 REST API。其非商业数据集是可下载的文件，商业访问需要授权，因此当前条款请查阅其文档。如果你想用 IMDb ID 调用一个 HTTP 接口并得到 JSON，amodb 在付费套餐中提供这一能力。如果你的合同要求使用 IMDb 自己授权的数据，那份协议要与 IMDb 签订，amodb 无法替代。

## 在 amodb 上使用 IMDb ID 的方式

五种调用覆盖了大多数需求。每一种都从你已有的 ID 出发，或以一个 ID 作为结果。

| 你已有或想要         | 调用                                              | 得到                                               |
| -------------- | ----------------------------------------------- | ------------------------------------------------ |
| 根据 IMDb ID 查作品 | `GET /3/find/tt0137523?external_source=imdb_id` | 数组 `movie_results`、`tv_results`、`person_results` |
| 电影的 IMDb ID    | `GET /3/movie/550`，字段 `imdb_id`                 | 《搏击俱乐部》的 `tt0137523`                             |
| 剧集的 IMDb ID    | `GET /3/tv/1396/external_ids`                   | `imdb_id`，与 TVDB ID 并列                           |
| IMDb 评分        | `GET /3/movie/550/ratings`                      | `imdb`，包含 `value` 和 `votes`，或为 null              |
| OMDb 风格的记录     | `GET /omdb/?i=tt0137523`                        | `imdbRating`、`imdbVotes`、`imdbID`                |

每一行都使用同一个密钥。评分在[评分](https://amodb.dev/zh/ratings/)页说明，ID 查找在[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)页说明。

## 读取 IMDb 评分

评分接口会同时返回分数和投票数。下面是《搏击俱乐部》（ID 550）的真实响应。分数会随时间变化。

```json
{
  "id": 550,
  "imdb": {
    "value": 8.8,
    "votes": 2669989
  },
  "kinopoisk": {
    "value": 8.7,
    "votes": null
  },
  "metacritic": {
    "value": 67,
    "votes": null
  },
  "rotten_tomatoes": {
    "value": 81,
    "votes": null
  },
  "tmdb": {
    "value": 8.437,
    "votes": 33039
  }
}
```

对 IMDb 而言，`value` 采用 0 到 10 的刻度，保留一位小数。请在旁边显示投票数，当对象为 `null` 时什么都不要渲染。在这个响应中，只有 IMDb 和 TMDB 带有投票数。任何来源的 `votes` 都可能是 `null`，显示之前请先检查。缓存的响应在边缘节点有效 6 小时，所以更频繁地轮询没有收益。

## 功能对比

| 功能   | IMDb                  | amodb                                     |
| ---- | --------------------- | ----------------------------------------- |
| 定价模式 | 商业访问需授权，请查阅其文档        | 预付，1 至 24 个月                              |
| 免费额度 | 没有免费的通用 REST API      | 无，也没有试用                                   |
| 认证方式 | 请查阅其文档                | `api_key` 查询参数或 Bearer 请求头                |
| 响应格式 | 可下载的数据集文件，授权数据源请查阅其文档 | JSON                                      |
| 语言   | 请查阅其文档                | 14 种界面语言                                  |
| 电影   | 字段请查阅其文档              | 详情、演职员、图片、视频                              |
| 电视剧  | 字段请查阅其文档              | 剧集、季、集                                    |
| 人物   | 字段请查阅其文档              | 资料、作品列表、图片                                |
| 图片   | 请查阅其文档                | `img.amodb.dev`，无需密钥                      |
| 评分   | 自有评分，访问方式请查阅其文档       | 已知时提供五个来源，其中包括 IMDb                       |
| 速率限制 | 请查阅其文档                | 每分钟 20、40 或 120 次请求                       |
| 商业使用 | 需授权，请查阅其文档            | 付费套餐，见[定价](https://amodb.dev/zh/pricing/) |
| 兼容性  | 自有格式，请查阅其文档           | TMDB v3 读取接口和 OMDb 协议                     |

## amodb 的不同之处

你调用的是接口，而不是解析文件。通过 `append_to_response`，一次请求就能返回作品及其演职员、预告片和评分，结构与 TMDB v3 一致，因此现有的客户端库可直接使用。同一个密钥也可用于 OMDb 风格的接口，让读取 `imdbRating` 的旧代码继续运行。

评分块是一个固定的对象，包含五个键。未知的来源为 `null`，而不是缺少键，因此读取 `ratings.imdb` 的代码不需要先检查上级对象是否存在。数值旁边可以有投票数，这样你可以隐藏只有少量投票支撑的评分。投票数也可能是 `null`，上面示例中五个来源里就有三个是这样。

## IMDb 更适合的场景

- **评分的源头。** IMDb 最先发布自己的评分。amodb 只在已知时返回数值，因此新作品或冷门作品可能返回 `null`。
- **站点功能。** 用户评论、列表和观看清单都在 IMDb 网站上。amodb 是元数据 API，不提供用户账户。
- **授权数据。** 如果合作方或合同要求使用 IMDb 授权的数据，只有 IMDb 能提供。
- **离线分析。** 非商业数据集文件适合在你自己的机器上进行批量研究。条款请查阅其文档。

## 迁移到 amodb

你很可能手上有一份 IMDb ID 列表。把每个 ID 映射到 amodb ID 一次，保存这一对，之后用数字 ID 调用详情。

```bash
curl -s "https://api.amodb.dev/3/find/tt0133093?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```python
import os
import requests

KEY = os.environ["AMODB_KEY"]
imdb_ids = ["tt0137523", "tt0133093", "tt1375666"]

for imdb_id in imdb_ids:
    r = requests.get(
        f"https://api.amodb.dev/3/find/{imdb_id}",
        params={"external_source": "imdb_id"},
        headers={"Authorization": f"Bearer {KEY}"},
        timeout=10,
    )
    r.raise_for_status()
    hits = r.json()["movie_results"]
    print(imdb_id, hits[0]["id"] if hits else None)
```

上面三个 ID 分别映射到 550、603 和 27205，即《搏击俱乐部》《黑客帝国》和《盗梦空间》。像 `tt0903747` 这样的剧集 ID 会出现在 `tv_results` 中，《绝命毒师》的 ID 是 1396。返回空数组表示该 ID 没有找到匹配项。

请控制循环的节奏。每个 ID 是一次请求，429 响应包含 `Retry-After` 头，给出需要等待的秒数。其他错误码见[错误](https://amodb.dev/zh/errors/)。

### 安全地保存 ID

- 把 IMDb ID 当作字符串保存。它们以 `tt` 开头并带有前导零，例如 `tt0137523`，而数字类型会丢掉这些零。
- 把 IMDb ID 和 amodb ID 成对保存。任何一个都能再次找到这部作品。
- 剧集读取 `tv_results`，电影读取 `movie_results`。一个 ID 通常只填充一个数组，其余保持为空。
- 之后都用 amodb ID 请求详情，因为详情调用可以通过 `append_to_response` 带上演职员、预告片和评分。

## 定价

从每分钟 20、40 或 120 个请求的三个套餐中选择一个，并预付 1、3、6、12 或 24 个月。更长的周期可享受 10、20、30 或 40% 的折扣。所有套餐返回的数据相同，都不会自动续费，也没有免费额度。具体金额见[定价](https://amodb.dev/zh/pricing/)。

## 常见问题

### IMDb 提供免费的 REST API 吗？

IMDb 没有免费的通用 REST API。其非商业数据集是可下载的文件，商业访问需要授权。在围绕它们做规划之前，请查阅其文档了解当前的条款、格式和字段。

### 能在 amodb 上用 IMDb ID 查找作品吗？

可以。调用 /3/find/tt0137523 并加上 external_source=imdb_id，然后读取 movie_results、tv_results 或 person_results。OMDb 风格的接口也接受带 IMDb ID 的 i 参数。

### IMDb 评分一定存在吗？

不一定。ratings 对象始终包含 imdb、kinopoisk、metacritic、rotten_tomatoes 和 tmdb 五个键，但评分未知时对应的值为 null。显示数字之前请先处理 null。

### 能获取 IMDb 用户评论或列表吗？

不能。amodb 返回 IMDb ID，以及已知时的 IMDb 评分和投票数。它不托管 IMDb 用户评论、列表或观看清单。TMDB 风格的评论接口返回 200，但大多数作品返回空列表。

### 映射一批 IMDb ID 需要多长时间？

每个 ID 一次 find 请求。500 个 ID 需要 500 次请求，所以在每分钟 20 次请求的套餐上大约需要 25 分钟。请保存结果，因为这种映射很少变化。

## 相关页面

- [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/): 用 TMDB find 接口按 IMDb、TVDB、Wikidata 或 Kinopoisk ID 查找电影、剧集或人物，并读取外部 ID。
- [电影与电视剧评分](https://amodb.dev/zh/ratings/): 一次调用返回作品的 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 评分，来源未知时为 null。
- [OMDb 兼容接口](https://amodb.dev/zh/omdb-endpoint/): 位于 api.amodb.dev/omdb/ 的 OMDb 兼容接口。用 i 或 t 查找，用 s 搜索，读取 Ratings 数组，只需更换基础 URL。
- [OMDb API 替代方案](https://amodb.dev/zh/omdb-api-alternative/): 碰到 OMDb 每日上限，或需要一次调用返回多条记录？amodb 可响应 OMDb 风格的请求，并用同一个密钥提供 TMDB v3 接口。
- [认证](https://amodb.dev/zh/authentication/): 如何发送 amodb 密钥：查询中的 api_key、Bearer 请求头，或 OMDb 的 apikey。含密钥格式、保管和 401 错误。
- [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。

更新于: 2026-10-18. Source: https://amodb.dev/zh/imdb-api-alternative/