包含状态、季和下一集的电视剧 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

完整的字段列表见电视剧和季与集。

三步开始

  1. 打开定价页，选择你需要的请求速率对应的套餐：每分钟 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 或更高版本运行。

bashjs 
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"
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 与你的用户关注的剧集进行匹配。季和集的详情见剧集指南页面。

构建带倒计时的关注列表

“我关注的剧集”页面需要为每部剧存一个 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 个请求的套餐上约需十分钟。见速率限制和错误。

对比

能力自己抓取页面免费层元数据 APIamodb
季和集的结构根据页面布局重建各不相同，请查阅文档带 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 个请求。见定价，创建密钥后，第一次剧集调用只需要一个请求。