TMDB API 替代方案

选择哪个 API

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

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

需要替代方案的信号

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

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

功能对比

amodb 的不同之处

• 看得见的限制。 每个带密钥的响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和以秒为单位的 X-RateLimit-Reset。429 响应还带有 Retry-After。这些数字在速率限制页中有说明。
• 一次调用获取额外数据块。 五个来源的评分、情绪指数、原声配乐、Wikidata 事实和影院放映场次都通过 append_to_response 返回，因此一个作品页可以只用一次请求。
• 更多外部 ID 来源。 /3/find 可解析 imdb_id、tvdb_id、wikidata_id 和 kinopoisk_id，也支持 facebook_id、twitter_id 和 instagram_id。见按外部 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。

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

迁移到 amodb

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

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 上分别运行现有测试。结构相同并不保证值完全一致，所以请对比你自己作品的一批样本。完整流程见快速开始，对照表见 amodb 与 TMDB。

错误处理可以沿用

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

请把 402 当作需要手动续费的信号，因为没有任何内容会自动续费。完整列表见错误。

定价

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