TheTVDB API 替代方案

哪一个适合电视剧项目

TheTVDB 专注于电视剧，在 API 密钥模式下为一部剧保存多种剧集排序，包括播出顺序、DVD 顺序和绝对顺序。规划商业产品之前，请查阅其文档了解授权条款。如果你希望用一个密钥获取剧集、电影和人物，并使用 TMDB v3 路径和 14 种语言，请选 amodb。如果精确的备用编号是你应用的核心，请选 TheTVDB，因为 amodb 会列出一部剧的剧集分组，但不提供分组内部的内容。

两者之间的电视剧数据如何对应

概念能对上，但名称不同。下表涵盖电视应用通常会读取的内容。

剧集字段使用 TMDB 的命名：air_date、episode_number、season_number、runtime 和 still_path。季和集的 external_ids 全为 null，因此无法从 amodb 读取单独某一季或某一集的 TVDB ID。请改用 season_number 和 episode_number 来关联。详情见季与集。

剧集分组列表返回什么

列表调用会显示一部剧存在哪些排序，但不会返回其中的剧集。

这是《绝命毒师》的真实响应。

{
  "id": 1396,
  "results": [
    {
      "description": "Seasons grouped as they appear on DVD, as well as paid video-on-demand services, such as Prime Video and YouTube.",
      "episode_count": 62,
      "group_count": 6,
      "id": "69f50757054263b7bc87e32a",
      "name": "DVD / PVOD",
      "network": null,
      "type": 3
    }
  ]
}

有些剧集只返回一种播出顺序，有些返回多种，还有些返回空的 results 数组。请测试你关心的剧集。由于分组的内容不提供，需要每一集 DVD 编号或绝对编号的应用无法从 amodb 得到它们。

功能对比

amodb 的不同之处

• 一个密钥覆盖整个目录。 一部剧集、它的演职员、预告片，以及与之共享演员的电影，都使用同一个基础 URL 和同一个限制。
• 评分与剧集指南放在一起。 在剧集详情上使用 append_to_response=ratings，一次调用即可加入 IMDb 和其他评分。
• 用简单的响应头控制节奏。 X-RateLimit-Remaining 和 X-RateLimit-Reset 告诉同步任务，60 秒窗口中还剩多少请求。
• 保留原始名称。 剧集保留 original_name，而 name 跟随你的 language，这在展示原生标题时很有用。

TheTVDB 更适合的场景

• 排序本身就是产品。 如果你的用户会争论 DVD 顺序、播出顺序和绝对顺序，TheTVDB 把这当作其模型的核心部分。amodb 会列出一部剧的排序名称，但不返回其中的剧集，而且不同剧集存在哪些分组也各不相同。
• 已有的集成。 如果你的流程已经保存 TheTVDB 的 ID 并读取它的排序，就保留这部分，再接入 amodb 获取额外数据。
• 专注电视剧。 如果你从不展示电影或人物，围绕电视剧构建的数据源需要学习的东西更少。

迁移到 amodb

把你已保存的 TVDB ID 映射一次。之后所有调用都使用 amodb ID。find 接口只解析剧集 ID，它的 tv_season_results 和 tv_episode_results 数组始终为空，所以季和集请按编号来映射。

const key = process.env.AMODB_KEY;
const headers = { Authorization: `Bearer ${key}` };
const base = 'https://api.amodb.dev/3';

async function getJson(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`${path} returned ${res.status}`);
  return res.json();
}

const found = await getJson('/find/81189?external_source=tvdb_id');
const show = found.tv_results[0];
console.log(show.id, show.name);

const groups = await getJson(`/tv/${show.id}/episode_groups`);
for (const g of groups.results) {
  console.log(g.name, g.type, g.episode_count);
}

第一个请求返回 ID 为 1396 的《绝命毒师》。第二个请求列出该剧存在的排序及其规模。要把编号与你目前保存的内容对比，请从 /tv/{id}/season/{n} 读取播出顺序，并把备用排序留在 TheTVDB 一侧。在迁移其余剧集之前，先对你最常看的十部剧做这项检查。

每次调用在 60 秒窗口中计为一个请求，429 响应带有 Retry-After。见按外部 ID 查找和速率限制。

定价

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