# TheTVDB API 替代方案

> TheTVDB 专注于电视剧，提供按播出、DVD 和绝对顺序等多种剧集排序。amodb 用一个密钥覆盖剧集、电影和人物，并一次调用把 TVDB ID 映射为自己的 ID。它列出剧集分组但不提供其内容，备用编号仍需使用 TheTVDB。

## 哪一个适合电视剧项目

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

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

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

| 需求       | TheTVDB 做法       | amodb 调用                              |
| -------- | ---------------- | ------------------------------------- |
| 单部剧集     | 按 TVDB ID 获取剧集记录 | 先做一次 `tvdb_id` 查找，再 `GET /3/tv/1396`  |
| 季列表      | 请查阅其文档           | 剧集详情中的 `seasons` 数组                   |
| 带剧集的一季   | 请查阅其文档           | `GET /3/tv/1396/season/1`             |
| 单集       | 请查阅其文档           | `GET /3/tv/1396/season/1/episode/1`   |
| 有哪些排序    | 播出、DVD 和绝对排序     | `GET /3/tv/1396/episode_groups`       |
| 某个排序中的剧集 | 请查阅其文档           | 不提供，`/3/tv/episode_group/{id}` 返回 404 |
| 下一集播出    | 请查阅其文档           | 剧集详情中的 `next_episode_to_air`          |

剧集字段使用 TMDB 的命名：`air_date`、`episode_number`、`season_number`、`runtime` 和 `still_path`。季和集的 `external_ids` 全为 null，因此无法从 amodb 读取单独某一季或某一集的 TVDB ID。请改用 `season_number` 和 `episode_number` 来关联。详情见[季与集](https://amodb.dev/zh/tv-seasons-episodes/)。

## 剧集分组列表返回什么

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

| 字段              | 含义                    |
| --------------- | --------------------- |
| `id`            | 分组的 ID，字符串            |
| `name`          | 排序的名称，例如 `DVD / PVOD` |
| `description`   | 来自数据源的文本，通常为空         |
| `type`          | 表示排序种类的数字             |
| `episode_count` | 该排序中的剧集数              |
| `group_count`   | 该排序中的分块数，例如季          |
| `network`       | 包含电视网的对象，或为 null      |

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

```json
{
  "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 得到它们。

## 功能对比

| 功能   | TheTVDB           | amodb                                     |
| ---- | ----------------- | ----------------------------------------- |
| 定价模式 | API 密钥模式，授权请查阅其文档 | 预付 1 至 24 个月                              |
| 免费额度 | 请查阅其文档            | 无，也没有试用                                   |
| 认证方式 | API 密钥，流程请查阅其文档   | `api_key` 或 Bearer 请求头                    |
| 响应格式 | JSON，请查阅其文档       | TMDB v3 格式的 JSON                          |
| 语言   | 请查阅其文档            | 14 种界面语言                                  |
| 电影   | 请查阅其文档            | 支持                                        |
| 电视剧  | 支持，这是其主要定位        | 支持，含季和集                                   |
| 人物   | 请查阅其文档            | 支持                                        |
| 图片   | 请查阅其文档            | `img.amodb.dev`，无需密钥                      |
| 评分   | 请查阅其文档            | 已知时提供 IMDb 及另外四个来源                        |
| 速率限制 | 请查阅其文档            | 每个密钥每分钟 20、40 或 120 次                     |
| 商业使用 | 授权请查阅其文档          | 付费套餐，见[定价](https://amodb.dev/zh/pricing/) |
| 兼容性  | 自有 API            | TMDB v3 读取接口和 OMDb                        |

## 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` 数组始终为空，所以季和集请按编号来映射。

```js
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 查找](https://amodb.dev/zh/find-by-external-id/)和[速率限制](https://amodb.dev/zh/rate-limits/)。

## 定价

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

## 常见问题

### 能把 TVDB ID 转换成 amodb ID 吗？

可以。用 external_source=tvdb_id 调用 /3/find/81189。tv_results 数组包含匹配的剧集，《绝命毒师》返回 ID 1396。请保存这一对，之后使用数字 ID。反向同样可行：/3/tv/1396/external_ids 会返回 tvdb_id。

### amodb 支持 DVD 顺序和绝对顺序吗？

只支持一部分。GET /3/tv/{id}/episode_groups 会列出一部剧的分组，包含 name、type、episode_count 和 group_count。分组的内容不提供，/3/tv/episode_group/{id} 返回 404。你能看到存在 DVD 排序，但读不到它的编号。

### TheTVDB 可以免费使用吗？

TheTVDB 采用 API 密钥模式，授权条款由 TheTVDB 制定。当前许可和费用请查阅其文档。amodb 是预付的付费 API，没有免费额度。

### 也能获取电影数据吗？

可以。电影、人物、图片、视频和译文与剧集使用同一个密钥和基础 URL。如果你的应用同时列出两者，就不需要再接入第二个数据提供方。

### 如何知道下一集何时播出？

剧集详情包含 next_episode_to_air 和 last_episode_to_air，各自带有 season_number、episode_number 和 air_date。对已完结的剧集，next 为 null。详情在边缘节点缓存 6 小时，因此每天最多轮询几次即可。

## 相关页面

- [电视剧季与单集 API](https://amodb.dev/zh/tv-seasons-episodes/): 路径和 JSON 与 TMDB v3 相同的电视剧季与单集 API。读取一季及其全部单集，或读取单集的播出日期、时长和剧照。
- [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/): 用 TMDB find 接口按 IMDb、TVDB、Wikidata 或 Kinopoisk ID 查找电影、剧集或人物，并读取外部 ID。
- [剧集指南 API](https://amodb.dev/zh/episode-guide-api/): 基于 TMDB v3 季与集接口的剧集指南 API：任意剧集的片名、播出日期、时长、剧照和剧集分组列表，支持 14 种语言。
- [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 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。

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