# 电视剧 API

> 电视剧接口通过 GET /3/tv/{series_id} 按 ID 返回一部剧：名称、简介、状态、季、电视网，以及上一集和下一集的指针。JSON 与 TMDB v3 一致，现有客户端只需更换基础地址。支持 append_to_response。

## 接口

`GET /3/tv/{series_id}`

```bash
curl "https://api.amodb.dev/3/tv/1396?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

响应:

```json
{
  "adult": false,
  "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg",
  "created_by": [],
  "episode_run_time": [
    48,
    49
  ],
  "first_air_date": "2008-01-20",
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "homepage": "",
  "id": 1396,
  "in_production": false,
  "languages": [
    "en"
  ],
  "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,
  "networks": [
    {
      "id": 174,
      "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png",
      "name": "AMC",
      "origin_country": "US"
    }
  ],
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "origin_country": [
    "US"
  ],
  "original_language": "en",
  "original_name": "Breaking Bad",
  "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial...",
  "popularity": 268.4968,
  "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg",
  "production_companies": [
    {
      "id": 2605,
      "logo_path": null,
      "name": "Gran Via Productions",
      "origin_country": "US"
    },
    {
      "id": 11073,
      "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png",
      "name": "Sony Pictures Television",
      "origin_country": "US"
    },
    {
      "id": 33742,
      "logo_path": "/2jdh2sEa0R6y6uT0F7g0IgA2WO8.png",
      "name": "High Bridge Productions",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    }
  ],
  "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 diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    },
    {
      "air_date": "2009-03-08",
      "episode_count": 13,
      "id": 3573,
      "name": "第 2 季",
      "overview": "贩卖冰毒的沃尔特老师在毒品交易中越陷越深，这引起了竞争对手的注意并使他在缉毒局的小舅子陷入危险中。",
      "poster_path": "/zMO024gJxKhTJfWqM0XTYd3SgKj.jpg",
      "season_number": 2,
      "vote_average": 0
    }
  ],
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    },
    {
      "english_name": "Spanish",
      "iso_639_1": "es",
      "name": "Español"
    }
  ],
  "status": "Ended",
  "tagline": "Change the equation.",
  "vote_average": 8.955,
  "vote_count": 18871
}
```

## 获取电视剧详情

`GET /3/tv/{series_id}` 返回一部剧的核心记录：名称、简介、状态、类型、电视网、季列表，以及指向上一集和下一集的指针。ID 是 TMDB 的数字电视剧 ID，所以你存为 `1396` 的剧在这里仍是这个 ID。电影 ID 和电视剧 ID 是各自独立的空间，所以请始终把媒体类型和数字一起保存。

示例用英文请求《绝命毒师》，并在同一次调用中追加它的内容分级和外部评分。

```bash
curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' });
const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const show = await res.json();
const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US');
console.log(show.name, show.status, show.number_of_seasons, us?.rating);
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/tv/1396",
    params={"language": "en-US", "append_to_response": "content_ratings,ratings"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
show = r.json()
us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None)
print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"])
```

```php
<?php
$url = 'https://api.amodb.dev/3/tv/1396?' . http_build_query([
    'language' => 'en-US',
    'append_to_response' => 'content_ratings,ratings',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$show = json_decode($body, true);
echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL;
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"
)

type Show struct {
	Name             string `json:"name"`
	Status           string `json:"status"`
	NumberOfSeasons  int    `json:"number_of_seasons"`
	NumberOfEpisodes int    `json:"number_of_episodes"`
	Next             *struct {
		AirDate string `json:"air_date"`
	} `json:"next_episode_to_air"`
}

func main() {
	q := url.Values{"language": {"en-US"}}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var s Show
	if err := json.NewDecoder(res.Body).Decode(&s); err != nil {
		panic(err)
	}
	next := "none scheduled"
	if s.Next != nil {
		next = s.Next.AirDate
	}
	fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next)
}
```

### 参数

| 参数                   | 位置 | 必填  | 说明                                                            |
| -------------------- | -- | --- | ------------------------------------------------------------- |
| `series_id`          | 路径 | 是   | 数字形式的电视剧 ID，例如 `1396`。                                        |
| `api_key`            | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。                     |
| `language`           | 查询 | 否   | `en-US`、`uk-UA` 或 `es-ES` 这样的 TMDB 标签。提供 14 种基础语言。默认 `en-US`。 |
| `append_to_response` | 查询 | 否   | 用逗号分隔的子资源列表，合并进响应，最多 20 个值。                                   |

### 响应字段

| 字段                                               | 类型             | 说明                                                                                                       |
| ------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------- |
| `id`                                             | integer        | 电视剧 ID。                                                                                                  |
| `name`、`original_name`                           | string         | 本地化标题和原始标题。日语或韩语的原名保留在 `original_name` 中。                                                                |
| `overview`、`tagline`                             | string         | 本地化文本，没有译文时为空。                                                                                           |
| `first_air_date`、`last_air_date`                 | string 或 null  | `YYYY-MM-DD`。                                                                                            |
| `status`                                         | string         | 生命周期，见下表。                                                                                                |
| `in_production`                                  | boolean        | 该剧仍在制作时为 `true`。                                                                                         |
| `number_of_seasons`、`number_of_episodes`         | integer        | 总数，按该剧存储的值。                                                                                              |
| `episode_run_time`                               | array          | 典型的单集时长，单位为分钟，可能为空。                                                                                      |
| `seasons`                                        | array          | 每季一条摘要，含 `id`、`season_number`、`name`、`overview`、`episode_count`、`air_date`、`poster_path`、`vote_average`。 |
| `last_episode_to_air`、`next_episode_to_air`      | object 或 null  | 单集摘要，结构与[季与单集](https://amodb.dev/zh/tv-seasons-episodes/)中的对象相同。                                         |
| `networks`、`production_companies`                | array          | `id`、`name`、`logo_path`、`origin_country`。                                                                |
| `production_countries`、`spoken_languages`        | array          | 国家含 `iso_3166_1` 和 `name`。语言含 `english_name`、`iso_639_1` 和 `name`。                                       |
| `created_by`                                     | array          | 创作者，含 `id`、`name`、`profile_path` 和 `credit_id`。大多数剧集为空。                                                  |
| `genres`                                         | array          | 含 `id` 和 `name` 的对象。电视剧的类型 ID 与电影不同。                                                                     |
| `origin_country`、`original_language`、`languages` | array、string   | 国家代码和语言代码。                                                                                               |
| `homepage`                                       | string         | 官方网站，未知时为空。                                                                                              |
| `poster_path`、`backdrop_path`                    | string 或 null  | 拼接到 `https://img.amodb.dev/t/p/{size}`。见[图片](https://amodb.dev/zh/images-api/)。                          |
| `popularity`                                     | number         | 热门榜单使用的相对分数。                                                                                             |
| `vote_average`、`vote_count`                      | number、integer | 汇总用户评分。                                                                                                  |
| `adult`                                          | boolean        | 始终为 `false`。成人作品永远不会提供。                                                                                  |

### 示例响应

`GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings`，较长的数组和文本已缩短：

```json
{
  "adult": false,
  "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg",
  "created_by": [],
  "episode_run_time": [
    48,
    49
  ],
  "first_air_date": "2008-01-20",
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "homepage": "",
  "id": 1396,
  "in_production": false,
  "languages": [
    "en"
  ],
  "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,
  "networks": [
    {
      "id": 174,
      "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png",
      "name": "AMC",
      "origin_country": "US"
    }
  ],
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "origin_country": [
    "US"
  ],
  "original_language": "en",
  "original_name": "Breaking Bad",
  "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...",
  "popularity": 268.4968,
  "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg",
  "production_companies": [
    {
      "id": 2605,
      "logo_path": null,
      "name": "Gran Via Productions",
      "origin_country": "US"
    },
    {
      "id": 11073,
      "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png",
      "name": "Sony Pictures Television",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    }
  ],
  "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 diagnosis. Stre...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    },
    {
      "english_name": "Spanish",
      "iso_639_1": "es",
      "name": "Español"
    }
  ],
  "status": "Ended",
  "tagline": "Change the equation.",
  "vote_average": 9,
  "vote_count": 18863,
  "content_ratings": {
    "results": [
      {
        "descriptors": [],
        "iso_3166_1": "AT",
        "rating": "16"
      },
      {
        "descriptors": [],
        "iso_3166_1": "AU",
        "rating": "MA 15+"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 9.5,
      "votes": 2671962
    },
    "kinopoisk": {
      "value": 8.9,
      "votes": null
    },
    "metacritic": null,
    "rotten_tomatoes": {
      "value": 96,
      "votes": null
    },
    "tmdb": {
      "value": 9,
      "votes": 18863
    }
  }
}
```

`content_ratings` 和 `ratings` 数据块来自 `append_to_response`。`seasons`、`last_episode_to_air` 和 `next_episode_to_air` 里的名称和简介是按记录存储的，可能不遵循 `language`，上面的希伯来语单集名称就是例子。本地化的季和单集文本请从[季接口](https://amodb.dev/zh/tv-seasons-episodes/)读取。

## 状态与单集指针

`status` 告诉你一部剧处于生命周期的哪个阶段，`next_episode_to_air` 告诉你何时该再来看看。

| `status` 值                | 含义           | `next_episode_to_air` |
| ------------------------- | ------------ | --------------------- |
| `Returning Series`        | 正在播出或处于两季之间。 | 日期已知时有值，否则为 null。     |
| `Planned`、`In Production` | 还不是常规剧集。     | 通常为 null。             |
| `Ended`                   | 已播完。         | null。                 |
| `Canceled`                | 在计划结束前停播。    | null。                 |

处于两季之间的在播剧，其 `next_episode_to_air` 为 null，所以请把 null 理解为没有已知日期，而不是已经完结。

`seasons` 数组为每一季列出一条摘要，第 `0` 季存放特别篇。要读取某一季的单集，请调用[季与单集](https://amodb.dev/zh/tv-seasons-episodes/)接口。

## 相关的电视剧接口

所有路径共用基础地址 `https://api.amodb.dev/3`，带本地化文本的接口也接受 `language`。

| 方法和路径                                    | 返回内容                                               | 额外参数   |
| ---------------------------------------- | -------------------------------------------------- | ------ |
| `GET /tv/{series_id}/alternative_titles` | `{id, results}`，含 `iso_3166_1`、`title`、`type`，通常为空 | 无      |
| `GET /tv/{series_id}/content_ratings`    | 各国的年龄分级                                            | 无      |
| `GET /tv/{series_id}/episode_groups`     | 备选单集顺序列表，例如 DVD 顺序或剧情线                             | 无      |
| `GET /tv/{series_id}/recommendations`    | 20 部推荐剧集的列表                                        | 无      |
| `GET /tv/{series_id}/similar`            | 20 部相似剧集的列表                                        | 无      |
| `GET /tv/{series_id}/reviews`            | 大多数剧集的 `results` 为空                                | 无      |
| `GET /tv/{series_id}/lists`              | 包含这部剧的公开片单                                         | `page` |
| `GET /tv/{series_id}/watch/providers`    | 各国的流媒体、租赁和购买平台                                     | 无      |
| `GET /tv/latest`                         | 最新添加的电视剧记录                                         | 无      |

推荐和相似列表始终返回第 1 页的 20 条。`lists` 响应用 `page` 分页，每页 20 个片单。API 其他位置的分页列表，`page` 范围为 1 到 500。

内容分级以 `results` 条目返回，含 `iso_3166_1`、`rating` 和 `descriptors`，所以请选择与访客所在国家匹配的条目。观看平台按国家代码索引，每个国家包含一个 `link` 以及 `flatrate`、`rent` 和 `buy` 列表，列表项有 `provider_id`、`provider_name`、`logo_path` 和 `display_priority`。用于筛选的平台 ID 来自[类型与查询列表](https://amodb.dev/zh/genres/)中的查询列表。

单集分组列表返回 `id`（字符串）、`name`、`description`、`type`、`episode_count`、`group_count` 和 `network`。amodb 会列出这些分组，但不提供返回某个分组单集的接口，也不提供 TMDB 的 `changes` 路径。

## 把更多数据合并进一次调用

在 `append_to_response` 中列出子资源，每个都会出现在各自的键下。整个调用只计入你每分钟 20、40 或 120 个请求中的一个。最多可用 20 个值，未知名称会被忽略且不报错。以下值适用于电视剧：

| 值                                                                                                                       | 添加内容                                     | 详情                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credits`                                                                                                               | 演员和幕后人员                                  | [演职员](https://amodb.dev/zh/credits/)                                                                                                                      |
| `external_ids`                                                                                                          | `imdb_id`、`tvdb_id` 和 `wikidata_id` 等 ID | [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)                                                                                                    |
| `images`、`videos`                                                                                                       | 海报、背景图、预告片                               | [图片](https://amodb.dev/zh/images-api/)、[视频与预告片](https://amodb.dev/zh/videos-trailers/)                                                                    |
| `keywords`、`translations`                                                                                               | 标签和译文                                    | [关键词](https://amodb.dev/zh/keywords/)、[翻译](https://amodb.dev/zh/translations/)                                                                            |
| `content_ratings`、`alternative_titles`、`episode_groups`、`lists`、`watch/providers`、`similar`、`recommendations`、`reviews` | 上表中的子资源                                  | 本页                                                                                                                                                        |
| `ratings`、`moods`、`soundtracks`、`wikidata`、`showtimes`                                                                  | amodb 扩展                                 | [评分](https://amodb.dev/zh/ratings/)、[情绪指数](https://amodb.dev/zh/moods/)、[原声配乐](https://amodb.dev/zh/soundtracks/)、[放映时间](https://amodb.dev/zh/showtimes/) |

## 错误

失败的调用返回 TMDB 的错误体。错误的 ID 会给出 `status_code` 34 和消息 "The resource you requested could not be found."。

| HTTP | status_code | 何时出现                          |
| ---- | ----------- | ----------------------------- |
| 401  | 7           | 密钥缺失或错误。                      |
| 402  | 36          | 套餐周期已结束。                      |
| 404  | 34          | 没有该 ID 的电视剧、成人作品，或不提供的路径。     |
| 405  | 37          | 你调用了写入方法，例如给剧集评分。             |
| 429  | 25          | 超过每分钟请求数。请等待 `Retry-After` 秒。 |

完整列表见[错误](https://amodb.dev/zh/errors/)，各套餐的限制见[速率限制](https://amodb.dev/zh/rate-limits/)。

## 实用说明

- 电视剧详情和上面所有子资源缓存 6 小时。轮询 `last_episode_to_air` 每天不要超过几次。
- 请求你要展示的语言。`overview` 为空表示没有译文，所以请用 `en-US` 重新请求作为回退。
- 获取每一季时，把 `number_of_seasons` 用作循环上限，每季一次调用。
- 要列出剧集而不是读取单部，请见[搜索](https://amodb.dev/zh/search/)、[发现 API](https://amodb.dev/zh/discover/)和[热门与榜单](https://amodb.dev/zh/trending-lists/)。

## 常见问题

### 如何判断一部剧是否仍在播出？

请把 status 与 next_episode_to_air 一起读取。状态为在播且 next_episode_to_air 不为 null 的剧，已经排好了一集。已完结和已取消的剧在这里始终返回 null，两季之间的剧也可能是 null。

### 电视剧记录包含 IMDb ID 吗？

与 TMDB 一样，基础记录中不包含。加上 append_to_response=external_ids 可获得 imdb_id 和 tvdb_id，或用 IMDb ID 调用 find 接口，从外部 ID 找到电视剧 ID。

### 能获得一部剧的 IMDb 和 Rotten Tomatoes 评分吗？

可以。调用 GET /3/tv/{series_id}/ratings 或加上 append_to_response=ratings。你会得到 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 的评分，每个都含 value 和 votes，未知时为 null。

### 电视剧数据缓存多久？

电视剧详情及其子资源在边缘缓存 6 小时，所以刚播出的单集可能延迟这么久才出现在 last_episode_to_air 中。像正在播出这样的榜单缓存 30 分钟。

## 相关页面

- [电视剧季与单集 API](https://amodb.dev/zh/tv-seasons-episodes/): 路径和 JSON 与 TMDB v3 相同的电视剧季与单集 API。读取一季及其全部单集，或读取单集的播出日期、时长和剧照。
- [演职员 API](https://amodb.dev/zh/credits/): 与 TMDB v3 路径和 JSON 相同的演职员 API。获取电影、剧集、季和集的演员与幕后人员，含 order、department 和 job 字段。
- [电影与电视剧评分](https://amodb.dev/zh/ratings/): 一次调用返回作品的 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 评分，来源未知时为 null。
- [用于剧集、季和集的电视剧 API](https://amodb.dev/zh/tv-show-api/): 电视剧 API：剧集状态、电视网、季、集和 next_episode_to_air。TMDB v3 兼容的 JSON，支持 14 种语言，每分钟 20 次起。
- [错误](https://amodb.dev/zh/errors/): amodb 的每个错误及其 HTTP 状态、TMDB status_code 和消息，以及 OMDb 错误结构。每个错误的含义和客户端下一步该做什么。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-19. Source: https://amodb.dev/zh/tv-series/