# 用于剧集、季和集的电视剧 API > 电视剧 API 通过 GET /3/tv/{series_id} 返回状态、电视网、季列表和 next_episode_to_air。季和集接口补充播出日期、时长和剧照。JSON 与 TMDB v3 一致，14 种语言，每分钟 20 至 120 个请求。 ## 包含状态、季和下一集的电视剧 API `GET /3/tv/{series_id}` 返回一部剧集及其 `status`、`networks`、`seasons` 列表、`last_episode_to_air` 和 `next_episode_to_air`。季和集接口增加播出日期、时长和剧照。amodb 是使用 TMDB v3 协议的独立 API，所以为 TMDB 编写的客户端，把基础 URL 改为 `https://api.amodb.dev/3` 后即可使用。 你会得到： - 带有季数和集数以及首播、最近播出日期的剧集记录。 - `status` 字符串和 `in_production` 标志。 - 带有 ID、标志和来源国家的电视网。 - 每季一次调用，返回该季的所有剧集。 - 今天或未来 7 天内播出的剧集列表。 ## 可获取的数据 | 你需要 | 调用 | 关键字段 | | -------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | 剧集记录 | `GET /3/tv/{series_id}` | `name`、`original_name`、`status`、`in_production`、`number_of_seasons`、`number_of_episodes` | | 下一集和最近一集 | 同一个调用 | `next_episode_to_air`、`last_episode_to_air` | | 单个季 | `GET /3/tv/{series_id}/season/{season_number}` | `episodes`、`air_date`、`poster_path` | | 单集 | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`、`overview`、`runtime`、`still_path`、`air_date` | | 电视网 | `GET /3/network/{network_id}` | `name`、`headquarters`、`origin_country` | 完整的字段列表见[电视剧](https://amodb.dev/zh/tv-series/)和[季与集](https://amodb.dev/zh/tv-seasons-episodes/)。 ## 三步开始 1. 打开[定价](https://amodb.dev/zh/pricing/)页，选择你需要的请求速率对应的套餐：每分钟 20、40 或 120 个。 2. 在账户后台创建 API 密钥。 3. 发送 `GET /3/tv/{series_id}`，带上 `Authorization: Bearer YOUR_API_KEY`，或把 `api_key` 作为查询参数。 ## 请求示例 脚本读取《绝命毒师》（剧集 ID 1396），打印它的状态和下一集，再列出第 1 季。把它保存为 `check.mjs`，用 Node 18 或更高版本运行。 ```bash curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \ -H "Authorization: Bearer $AMODB_KEY" curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const show = await get('/tv/1396?language=en-US'); const next = show.next_episode_to_air; console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`); console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode is scheduled'); const season = await get('/tv/1396/season/1?language=en-US'); for (const ep of season.episodes) { console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`); } ``` `language=en-US` 的精简剧集响应。只保留了部分字段，`seasons` 显示 6 项中的前 2 项。在这份数据中，有些名称不遵循 `language`：第 0 季的名称是中文，`last_episode_to_air` 里的 `name` 是希伯来文。 ```json { "first_air_date": "2008-01-20", "id": 1396, "in_production": false, "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "number_of_episodes": 62, "number_of_seasons": 5, "original_name": "Breaking Bad", "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagn...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "status": "Ended" } ``` ## 读取状态和下一集 `status` 字符串告诉你该如何标注一部剧集。只有在有剧集排期时，`next_episode_to_air` 才是对象，因此季间休息期和完结之后它都是 null。在显示“已完结”之前，请先检查 `status`。 | `status` | 含义 | 显示什么 | | ---------------- | --------- | -------------------------- | | Returning Series | 预计还有更多剧集 | 如果对象存在则显示下一集播出日期，否则显示“续订中” | | In Production | 制作中，尚未播出 | “制作中” | | Planned | 仅已宣布 | “计划中” | | Pilot | 只有试播集 | “试播” | | Ended | 已播完 | “已完结”和 `last_air_date` | | Canceled | 在计划结束前被终止 | “已取消” | `next_episode_to_air` 和 `last_episode_to_air` 内部的字段：`air_date`、`season_number`、`episode_number`、`episode_type`、`id`、`show_id`、`name`、`overview`、`runtime` 和 `still_path`。个别作品的 `status` 字符串也可能为空，所以请准备一个中性的标签。 详情在边缘缓存 6 小时，因此一天内多于四次请求同一部剧集，返回的内容相同。请对用户关注的剧集每天轮询一两次，并在用户打开某一部时刷新它。 ## 季、集和正在播出的内容 第 0 季（如果剧集有的话）存放特别篇。正常的季从 1 开始。 | 调用 | 返回 | 参数 | | ---------------------------------------------- | -------------------- | ---------------------------------------------- | | `GET /3/tv/{series_id}/season/{season_number}` | 带有 `episodes` 数组的季记录 | `language`、`append_to_response` | | `GET /3/tv/airing_today` | 今天有剧集播出的电视剧 | `page`、`language` | | `GET /3/tv/on_the_air` | 未来一周内播出的电视剧 | `page`、`language` | | `GET /3/discover/tv` | 按电视网、状态等筛选的电视剧 | `with_networks`、`with_status`、`sort_by`、`page` | 列表和 discover 结果缓存 30 分钟，所以每半小时一次请求就足以支撑“即将播出”徽章。请把返回的 ID 与你的用户关注的剧集进行匹配。季和集的详情见[剧集指南](https://amodb.dev/zh/episode-guide-api/)页面。 ## 构建带倒计时的关注列表 “我关注的剧集”页面需要为每部剧存一个 ID，外加一个小型每日任务。 1. 用户关注一部剧时，保存剧集的 `id`。 2. 每天对每个已关注的 ID 调用一次 `/3/tv/{series_id}`，并保存 `status`、`next_episode_to_air` 和 `last_air_date`。 3. 当 `next_episode_to_air` 是对象时，把 `air_date` 显示为日期。它不包含具体时刻和时区，所以不要精确到分钟倒计时。 4. 当它为 null 且 `status` 为 Returning Series 时，显示“新一季尚未排期”。 5. 只有在用户打开某部剧时才获取季调用，因为它是最大的响应。 404 且 `status_code` 为 34 表示 ID 未知，429 表示你超出了每分钟请求数：请等待 `Retry-After` 秒。关注 200 部剧时，每天遍历一次是 200 个请求，在每分钟 20 个请求的套餐上约需十分钟。见[速率限制](https://amodb.dev/zh/rate-limits/)和[错误](https://amodb.dev/zh/errors/)。 ## 对比 | 能力 | 自己抓取页面 | 免费层元数据 API | amodb | | ------- | ---------- | ---------- | ----------------------------------------- | | 季和集的结构 | 根据页面布局重建 | 各不相同，请查阅文档 | 带 `episodes` 数组的季调用 | | 下一次播出日期 | 从排期页面解析 | 各不相同，请查阅文档 | `next_episode_to_air`，无排期时为 null | | 剧集状态 | 页面上的自由文本 | 各不相同，请查阅文档 | `status` 字符串和 `in_production` 标志 | | 本周播出 | 抓取排期页 | 各不相同，请查阅文档 | `/3/tv/on_the_air` 和 `/3/tv/airing_today` | | 语言 | 页面提供什么就是什么 | 各不相同 | 14 种，用 `language` 选择 | | 访问条款 | 适用网站的条款 | 免费层附带使用条款 | 付费，预付，无免费额度 | ## 定价 一次性预付 1、3、6、12 或 24 个月。较长的周期可享受 10、20、30 或 40% 的折扣，也不会自动续费。每个套餐都能获取全部电视剧数据，唯一的区别是每分钟 20、40 或 120 个请求。见[定价](https://amodb.dev/zh/pricing/)，创建密钥后，第一次剧集调用只需要一个请求。 ## 常见问题 ### 如何知道一部电视剧是否仍在播出？ 读取 /3/tv/{id} 上的 status。Returning Series 表示预计还有更多剧集，Ended 和 Canceled 表示没有了。next_episode_to_air 字段保存下一个已排期的剧集，没有排期时为 null。 ### 能在一次请求中获取一部剧的所有剧集吗？ 每次调用一季。GET /3/tv/{id}/season/{n} 会在 episodes 数组中返回该季的全部剧集，所以一部五季的剧需要五次季调用加一次剧集调用。 ### 电视网能获取到什么？ 剧集上的 networks 数组列出 id、name、logo_path 和 origin_country。GET /3/network/{id} 提供更多详情，/3/discover/tv 中的 with_networks 可列出某个电视网的剧集。 ### 能列出今天播出的剧集吗？ 能。/3/tv/airing_today 列出今天有剧集播出的电视剧，/3/tv/on_the_air 覆盖未来 7 天。两者都分页，支持 language，并在边缘缓存 30 分钟。 ### 电视剧 API 有免费额度吗？ 没有免费额度，也没有试用。你可以预付 1、3、6、12 或 24 个月，不会自动续费。每个套餐返回全部数据，区别只在于每分钟请求数。 ## 相关页面 - [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 ID 获取剧集的季、电视网和下一集，以及内容分级和观看平台。 - [电视剧季与单集 API](https://amodb.dev/zh/tv-seasons-episodes/): 路径和 JSON 与 TMDB v3 相同的电视剧季与单集 API。读取一季及其全部单集，或读取单集的播出日期、时长和剧照。 - [剧集指南 API](https://amodb.dev/zh/episode-guide-api/): 基于 TMDB v3 季与集接口的剧集指南 API：任意剧集的片名、播出日期、时长、剧照和剧集分组列表，支持 14 种语言。 - [公司与电视网](https://amodb.dev/zh/companies-networks/): 按 TMDB v3 路径查询制作公司和电视网：按 ID 读取名称、国家和标志，再按公司或电视网 ID 筛选 discover。 - [热门与榜单接口](https://amodb.dev/zh/trending-lists/): 兼容 TMDB v3 路径的热门电影 API：日榜与周榜，以及电影和电视剧的正在上映、热门、高分、即将上映榜单，缓存 30 分钟。 - [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。 更新于: 2026-10-18. Source: https://amodb.dev/zh/tv-show-api/