# TMDB API 替代方案

> 当你需要付费协议、可规划的请求限制，或每次响应包含更多数据时，可以考虑 TMDB API 替代方案。amodb 的读取接口遵循 TMDB v3 协议，你只需更换基础 URL 和密钥。写入和少数路径不提供。如果 TMDB 的免费条款适合你，就继续使用它。

## 选择哪个 API

TMDB 对符合条件的使用按其自身条款提供免费 API，有 API v3 密钥和 v4 令牌。发布之前，请阅读其关于商业使用和署名的条款。当你需要付费协议、可规划的限制，或每次响应包含更多数据时，可以选择替代方案。amodb 是独立的 API，读取部分遵循 TMDB v3 协议，因此切换只需要新的基础 URL 和新的密钥。它是只读的，少数 TMDB 路径不提供，详见下文。

如果免费条款适合你的项目，而且下一节的情况都不适用，就继续使用 TMDB。

## 需要替代方案的信号

五项检查可以帮助你决定。请用你自己的流量和合同来检验，而不是对照功能清单。

| 信号    | 要检验什么                     | amodb 的回答                                                                         |
| ----- | ------------------------- | --------------------------------------------------------------------------------- |
| 商业条款  | 阅读你目前使用的 API 关于商业使用和署名的条款 | 付费套餐，预付，不自动续费                                                                     |
| 峰值流量  | 统计你最忙那一分钟的请求数             | 每个密钥每分钟固定 20、40 或 120 个请求                                                         |
| 每屏数据量 | 列出一个作品页背后的额外调用            | `append_to_response` 还接受 `ratings`、`moods`、`soundtracks`、`wikidata` 和 `showtimes` |
| 界面语言  | 检查你发布的每一种语言               | 14 种语言，其余回退到 `en`                                                                 |
| 退出成本  | 统计代码中点名某个供应商的行数           | 已提供的接口路径和 JSON 相同，因此离开时同样只需更换基础 URL                                               |

缓存命中也会计数。密钥检查和速率限制先于边缘缓存执行，所以重复的请求仍然占用你每分钟请求数中的一个。请按总请求数来规划，而不是按缓存未命中数。

## 功能对比

| 功能   | TMDB                                  | amodb                                                     |
| ---- | ------------------------------------- | --------------------------------------------------------- |
| 定价模式 | 符合条件的使用按其自身条款免费                       | 预付 1、3、6、12 或 24 个月                                       |
| 免费额度 | 有，限符合条件的使用                            | 无，也没有试用                                                   |
| 认证方式 | `api_key` 中的 v3 密钥，或作为 Bearer 的 v4 令牌 | `api_key` 或 Bearer，32 位十六进制密钥                             |
| 响应格式 | JSON                                  | TMDB v3 格式的 JSON                                          |
| 语言   | 请查阅其文档                                | 14 种界面语言                                                  |
| 电影   | 支持                                    | 支持                                                        |
| 电视剧  | 支持                                    | 支持，含季和集                                                   |
| 人物   | 支持                                    | 支持                                                        |
| 图片   | 支持，来自其自有图片主机                          | `img.amodb.dev`，尺寸标识相同，无需密钥                               |
| 评分   | TMDB 用户评分，其他来源请查阅其文档                  | TMDB 评分，另有已知的 IMDb、Kinopoisk、Metacritic 和 Rotten Tomatoes |
| 写入方法 | 账户、列表和评分方法                            | 不提供，返回 405                                                |
| 速率限制 | 请查阅其文档                                | 每个密钥每分钟 20、40 或 120 次                                     |
| 商业使用 | 商业使用和署名要求请查看其条款                       | 作为付费 API 出售，见[定价](https://amodb.dev/zh/pricing/)          |
| 兼容性  | 定义了 v3 协议                             | 大多数 v3 读取路径，另有 OMDb                                       |

## amodb 的不同之处

- **看得见的限制。** 每个带密钥的响应都包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和以秒为单位的 `X-RateLimit-Reset`。429 响应还带有 `Retry-After`。这些数字在[速率限制](https://amodb.dev/zh/rate-limits/)页中有说明。
- **一次调用获取额外数据块。** 五个来源的评分、情绪指数、原声配乐、Wikidata 事实和影院放映场次都通过 `append_to_response` 返回，因此一个作品页可以只用一次请求。
- **更多外部 ID 来源。** `/3/find` 可解析 `imdb_id`、`tvdb_id`、`wikidata_id` 和 `kinopoisk_id`，也支持 `facebook_id`、`twitter_id` 和 `instagram_id`。见[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)。
- **同一个密钥使用 OMDb。** `https://api.amodb.dev/omdb/` 通过 `apikey` 参数响应 OMDb 风格的调用，当你的两个系统使用不同协议时很有用。
- **明确的缓存时间。** 详情和演职员在边缘缓存 6 小时，热门趋势和发现 30 分钟，搜索 10 分钟，配置 24 小时，图片 30 天。

## TMDB 更适合的场景

- **免费项目。** 如果你的使用符合免费条款，TMDB 不花一分钱，这一点 amodb 无法比拟。
- **用户写入方法。** TMDB 提供账户、会话、评分和列表的写入方法。amodb 对它们返回 405 和 status_code 37，因此允许用户登录并给作品评分的应用，应在这一部分继续使用 TMDB。
- **变更动态。** TMDB 会列出发生变化的 ID。amodb 没有这类动态，你需要按自己的计划刷新。
- **超出 14 种的语言。** amodb 不提供德语、日语或韩语的界面文本，会回退到英语。原始片名仍会出现在 `original_title` 和 `original_name` 中。TMDB 上其他语言的情况请查阅其文档。
- **已接受的条款。** 如果 TMDB 的法务审查已经完成，切换就意味着要再审查一次。

## amodb 不提供什么

切换之前，请对照这份清单检查你的代码。完整的表格见 [amodb 与 TMDB](https://amodb.dev/zh/amodb-vs-tmdb/)。

| TMDB 调用                    | amodb 的响应            |
| -------------------------- | -------------------- |
| 账户、会话、评分和列表的写入             | 405，`status_code` 37 |
| 变更、聚合演职员、单条演职员和评论查询、剧集分组内容 | 404，`status_code` 34 |
| 人物译文，系列合集、公司和电视网的图片与译文     | 404，`status_code` 34 |
| 电影或剧集的评论列表                 | 200，大多数作品为空          |
| 季的图片、视频和译文                 | 200，为空               |
| 季和集的外部 ID                  | 200，全部为 null         |

有两种行为不会报错。amodb 不认识的 `append_to_response` 名称，例如 `aggregate_credits`，会被忽略而不返回错误。`include_adult` 参数同样被忽略，因为成人影视作品和人物从不提供。

## 迁移到 amodb

1. 在[定价](https://amodb.dev/zh/pricing/)页选择套餐，然后在账户后台创建密钥。
2. 在同一个位置替换基础 URL 和密钥，如下所示。
3. 从 `/3/configuration` 读取 `images.secure_base_url`，让图片链接使用 `img.amodb.dev`。
4. 删除对写入方法和上表所列路径的调用。
5. 处理 429：等待 `Retry-After` 指定的秒数。

```js
const config = {
  // before: baseUrl held your current TMDB v3 base URL
  baseUrl: 'https://api.amodb.dev/3',
  apiKey: process.env.AMODB_KEY,
};

const res = await fetch(`${config.baseUrl}/movie/550?language=en-US`, {
  headers: { Authorization: `Bearer ${config.apiKey}` },
});
if (!res.ok) throw new Error(`request failed with status ${res.status}`);
const movie = await res.json();
console.log(movie.title, movie.release_date);
```

切换之前，请在两个基础 URL 上分别运行现有测试。结构相同并不保证值完全一致，所以请对比你自己作品的一批样本。完整流程见[快速开始](https://amodb.dev/zh/quickstart/)，对照表见 [amodb 与 TMDB](https://amodb.dev/zh/amodb-vs-tmdb/)。

### 错误处理可以沿用

失败的调用返回 TMDB 的响应体 `{"success": false, "status_code": N, "status_message": "..."}`，因此基于 `status_code` 分支的代码无需重写。

| HTTP | status_code | 常见原因                  |
| ---- | ----------- | --------------------- |
| 401  | 7           | 密钥缺失或拼写错误             |
| 401  | 10          | 密钥已停用                 |
| 402  | 36          | 预付周期已结束               |
| 404  | 34          | 找不到 ID，或 amodb 不提供的路径 |
| 405  | 37          | 你的代码仍在调用的写入方法         |
| 429  | 25          | 60 秒内的请求数超出套餐允许值      |

请把 402 当作需要手动续费的信号，因为没有任何内容会自动续费。完整列表见[错误](https://amodb.dev/zh/errors/)。

## 定价

amodb 采用预付方式。可选择 1、3、6、12 或 24 个月的周期，分别享受 0、10、20、30 或 40% 的折扣，并在每分钟 20、40 或 120 个请求的三个套餐中选择一个。所有套餐都能获取全部数据，也都不会自动续费。没有免费额度，也没有试用。当前金额见[定价](https://amodb.dev/zh/pricing/)。

## 常见问题

### amodb 能直接替换 TMDB API 吗？

对大多数读取接口来说可以。路径、查询参数和 JSON 字段遵循 TMDB v3，api_key 和 Bearer 认证都可用。写入方法返回 405，status_code 为 37。变更动态、聚合演职员、单条演职员和评论查询以及其他少数路径返回 404，status_code 为 34。

### 我现有的 TMDB 图片 URL 还能用吗？

路径结构和尺寸标识保持不变，但主机是 img.amodb.dev，且无需密钥。请从配置接口读取 images.secure_base_url，而不要硬编码主机，图片相关代码无需其他改动。

### amodb 像 TMDB 一样接受 Bearer 请求头吗？

接受。用你的 amodb 密钥发送 Authorization: Bearer，或传入 api_key 查询参数。密钥是 32 位小写十六进制字符，与 TMDB v3 密钥的形式相同。

### 费用与免费的 TMDB API 相比如何？

TMDB 对符合条件的使用按其自身条款提供免费 API。amodb 没有免费额度，也没有试用。你可以在三个套餐之一上预付 1 至 24 个月，当前金额见定价页。

### 应该按哪个限制来规划？

按你最忙的那一分钟来选。套餐允许每个密钥在 60 秒滑动窗口内每分钟 20、40 或 120 个请求，所有套餐返回全部数据。响应头会显示剩余请求数。

## 相关页面

- [amodb 与 TMDB 对比](https://amodb.dev/zh/amodb-vs-tmdb/): amodb 与 TMDB 正面对比：接口兼容程度、amodb 未提供的路径、免费与付费条款、14 种语言、扩展功能和速率限制。
- [OMDb API 替代方案](https://amodb.dev/zh/omdb-api-alternative/): 碰到 OMDb 每日上限，或需要一次调用返回多条记录？amodb 可响应 OMDb 风格的请求，并用同一个密钥提供 TMDB v3 接口。
- [用于自建片库的电影数据库 API](https://amodb.dev/zh/movie-database-api/): 用于自建本地副本的电影数据库 API：电影、人物、公司、系列合集和关键词的关联 ID、discover 日期窗口与 ID 查找。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。
- [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。
- [定价](https://amodb.dev/zh/pricing/): amodb 套餐的区别只在每分钟请求数：20、40 或 120。所有套餐都包含全部兼容 TMDB v3 和 OMDb 的数据。预付，不续费，无试用。

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