# 演职员 API

> 演职员接口返回电影的演员和幕后人员（GET /3/movie/{movie_id}/credits），剧集、季、集在 /3/tv 下。JSON 与 TMDB v3 一致，含 credit_id、order、job。单集增加 guest_stars。

## 接口

`GET /3/movie/{movie_id}/credits`

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

响应:

```json
{
  "id": 27205,
  "cast": [
    {
      "adult": false,
      "gender": 2,
      "id": 6193,
      "known_for_department": "Acting",
      "name": "Leonardo DiCaprio",
      "original_name": "Leonardo DiCaprio",
      "popularity": 9.3213,
      "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
      "character": "Dom Cobb",
      "credit_id": "52fe4534c3a368484e04de03",
      "order": 0
    },
    {
      "adult": false,
      "gender": 2,
      "id": 24045,
      "known_for_department": "Acting",
      "name": "Joseph Gordon-Levitt",
      "original_name": "Joseph Gordon-Levitt",
      "popularity": 5.6202,
      "profile_path": "/z2FA8js799xqtfiFjBTicFYdfk.jpg",
      "character": "Arthur",
      "credit_id": "52fe4534c3a368484e04de0b",
      "order": 1
    },
    {
      "adult": false,
      "gender": 2,
      "id": 3899,
      "known_for_department": "Acting",
      "name": "Ken Watanabe",
      "original_name": "Ken Watanabe",
      "popularity": 3.1459,
      "profile_path": "/psAXOYp9SBOXvg6AXzARDedNQ9P.jpg",
      "character": "Saito",
      "credit_id": "52fe4534c3a368484e04de07",
      "order": 2
    }
  ],
  "crew": [
    {
      "adult": false,
      "gender": 2,
      "id": 1025090,
      "known_for_department": "Crew",
      "name": "Jim Wilkey",
      "original_name": "Jim Wilkey",
      "popularity": 0.9114,
      "profile_path": "/peEdS7ZYHwEeMJAwInJj732AeYs.jpg",
      "credit_id": "6634553bad59b501286dab5f",
      "department": "Crew",
      "job": "Stunt Driver"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1741194,
      "known_for_department": "Sound",
      "name": "James Thatcher",
      "original_name": "James Thatcher",
      "popularity": 0.6215,
      "profile_path": null,
      "credit_id": "5bcdece8925141613e0216d3",
      "department": "Sound",
      "job": "Musician"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1899036,
      "known_for_department": "Crew",
      "name": "Kyle Photo Bucher",
      "original_name": "Kyle Photo Bucher",
      "popularity": 0,
      "profile_path": null,
      "credit_id": "5bcdfa639251416134024237",
      "department": "Crew",
      "job": "Set Production Assistant"
    }
  ]
}
```

## 获取电影演职员

`GET /3/movie/{movie_id}/credits` 为一部电影返回两个数组：`cast` 是出镜的人，`crew` 是幕后工作的人。每一项都带有人物 ID，所以你可以在[人物](https://amodb.dev/zh/people/)页中打开完整记录。同样的数据也可以通过 `append_to_response=credits` 包含在电影响应中。

示例读取《盗梦空间》，打印导演并列出署名前五位的演员。

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

```js
const url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const credits = await res.json();
const director = credits.crew.find((c) => c.job === 'Director');
console.log('Director:', director?.name);
for (const c of [...credits.cast].sort((a, b) => a.order - b.order).slice(0, 5)) {
  console.log(c.order, c.name, 'as', c.character);
}
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/27205/credits",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
credits = r.json()
director = next((c for c in credits["crew"] if c["job"] == "Director"), None)
print("Director:", director and director["name"])
for c in sorted(credits["cast"], key=lambda c: c["order"])[:5]:
    print(c["order"], c["name"], "as", c["character"])
```

```php
<?php
$url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
$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");
}
$credits = json_decode($body, true);
usort($credits['cast'], fn ($a, $b) => $a['order'] <=> $b['order']);
foreach (array_slice($credits['cast'], 0, 5) as $c) {
    echo $c['order'], ' ', $c['name'], ' as ', $c['character'], PHP_EOL;
}
```

```go
package main

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

type Credits struct {
	Cast []struct {
		Order     int    `json:"order"`
		Name      string `json:"name"`
		Character string `json:"character"`
	} `json:"cast"`
	Crew []struct {
		Name string `json:"name"`
		Job  string `json:"job"`
	} `json:"crew"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/27205/credits?language=en-US", 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 c Credits
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	for _, m := range c.Crew {
		if m.Job == "Director" {
			fmt.Println("Director:", m.Name)
		}
	}
	for i, a := range c.Cast {
		if i == 5 {
			break
		}
		fmt.Println(a.Order, a.Name, "as", a.Character)
	}
}
```

### 参数

| 参数         | 位置 | 必填  | 说明                                                   |
| ---------- | -- | --- | ---------------------------------------------------- |
| `movie_id` | 路径 | 是   | 数字形式的电影 ID，例如 `27205`。                               |
| `api_key`  | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。            |
| `language` | 查询 | 否   | `en-US` 或 `fr-FR` 这样的 TMDB 标签。14 种基础语言之外的标签回退到 `en`。 |

### 响应字段

| 字段                            | 适用于     | 说明                                                                                                                                  |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                          | 顶层      | 演职员所属的电影、剧集、季或集的 ID。                                                                                                                |
| `cast`、`crew`                 | 顶层      | 条目数组。单集演职员增加 `guest_stars`。                                                                                                         |
| `id`                          | 每个条目    | 人物 ID。用[人物](https://amodb.dev/zh/people/)打开它。                                                                                       |
| `name`、`original_name`        | 每个条目    | 人物的姓名。                                                                                                                              |
| `known_for_department`        | 每个条目    | 此人总体上的主要工作，而不是在本作品中的工作。                                                                                                             |
| `gender`、`popularity`、`adult` | 每个条目    | 含义与人物记录相同。                                                                                                                          |
| `profile_path`                | 每个条目    | 图片路径或 null。拼接到 `https://img.amodb.dev/t/p/{size}`。                                                                                  |
| `credit_id`                   | 每个条目    | 标识这一条演职员记录的字符串。                                                                                                                     |
| `character`                   | 演员、客串演员 | 角色名，有些条目为空。                                                                                                                         |
| `order`                       | 演员、客串演员 | 署名位置，`0` 表示第一。                                                                                                                      |
| `department`                  | 幕后人员    | 分组，例如 `Directing`、`Writing`、`Production`、`Camera`、`Editing`、`Sound`、`Art`、`Visual Effects`、`Lighting`、`Costume & Make-Up` 或 `Crew`。 |
| `job`                         | 幕后人员    | 具体职务，例如 `Director`、`Screenplay` 或 `Editor`。                                                                                         |

### 示例响应

`GET /3/movie/27205/credits?language=en-US`。该响应目前有 52 条演员和 735 条幕后人员记录，所以这里两个数组都缩减为两条：

```json
{
  "id": 27205,
  "cast": [
    {
      "adult": false,
      "gender": 2,
      "id": 6193,
      "known_for_department": "Acting",
      "name": "Leonardo DiCaprio",
      "original_name": "Leonardo DiCaprio",
      "popularity": 9.3213,
      "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
      "character": "Dom Cobb",
      "credit_id": "52fe4534c3a368484e04de03",
      "order": 0
    },
    {
      "adult": false,
      "gender": 2,
      "id": 24045,
      "known_for_department": "Acting",
      "name": "Joseph Gordon-Levitt",
      "original_name": "Joseph Gordon-Levitt",
      "popularity": 5.6202,
      "profile_path": "/z2FA8js799xqtfiFjBTicFYdfk.jpg",
      "character": "Arthur",
      "credit_id": "52fe4534c3a368484e04de0b",
      "order": 1
    }
  ],
  "crew": [
    {
      "adult": false,
      "gender": 2,
      "id": 1025090,
      "known_for_department": "Crew",
      "name": "Jim Wilkey",
      "original_name": "Jim Wilkey",
      "popularity": 0.9114,
      "profile_path": "/peEdS7ZYHwEeMJAwInJj732AeYs.jpg",
      "credit_id": "6634553bad59b501286dab5f",
      "department": "Crew",
      "job": "Stunt Driver"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1741194,
      "known_for_department": "Sound",
      "name": "James Thatcher",
      "original_name": "James Thatcher",
      "popularity": 0.6215,
      "profile_path": null,
      "credit_id": "5bcdece8925141613e0216d3",
      "department": "Sound",
      "job": "Musician"
    }
  ]
}
```

## 电视剧、季和集的演职员

下面所有路径共用基础地址 `https://api.amodb.dev/3`，并接受 `language`。

| 方法和路径                                                                         | 返回内容                                    |
| ----------------------------------------------------------------------------- | --------------------------------------- |
| `GET /tv/{series_id}/credits`                                                 | 剧集的演员和幕后人员，每个人每个角色一条。                   |
| `GET /tv/{series_id}/season/{season_number}/credits`                          | 一季的演员和幕后人员。                             |
| `GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits` | 一集的 `crew` 和 `guest_stars`。`cast` 是空数组。 |

在剧集、季和集的路径上用 `append_to_response=credits` 也能获得同样的数据。条目的结构与上面的电影演职员相同。单集的客串演员带有 `character` 和 `order`，幕后人员条目带有 `department` 和 `job`。

`GET /3/tv/1399/season/1/episode/1/credits?language=en-US`，数组缩减为两条：

```json
{
  "id": 63056,
  "cast": [],
  "crew": [
    {
      "department": "Writing",
      "job": "Writer",
      "credit_id": "5256c8a019c2956ff6046e2b",
      "adult": false,
      "gender": 2,
      "id": 9813,
      "known_for_department": "Writing",
      "name": "David Benioff",
      "original_name": "David Benioff",
      "popularity": 2.0354,
      "profile_path": "/xvNN5huL0X8yJ7h3IZfGG4O2zBD.jpg"
    },
    {
      "department": "Editing",
      "job": "Editor",
      "credit_id": "54eef2ab925141795f005d4f",
      "adult": false,
      "gender": 2,
      "id": 18077,
      "known_for_department": "Editing",
      "name": "Oral Norrie Ottey",
      "original_name": "Oral Norrie Ottey",
      "popularity": 0,
      "profile_path": null
    }
  ],
  "guest_stars": [
    {
      "character": "Benjen Stark",
      "credit_id": "5256c8b919c2956ff604836a",
      "order": 61,
      "adult": false,
      "gender": 2,
      "id": 119783,
      "known_for_department": "Acting",
      "name": "Joseph Mawle",
      "original_name": "Joseph Mawle",
      "popularity": 1.4645,
      "profile_path": "/1Ocb9v3h54beGVoJMm4w50UQhLf.jpg"
    },
    {
      "character": "Rickon Stark",
      "credit_id": "566a83bcc3a3683f56003604",
      "order": 80,
      "adult": false,
      "gender": 2,
      "id": 1050248,
      "known_for_department": "Acting",
      "name": "Art Parkinson",
      "original_name": "Art Parkinson",
      "popularity": 1.2594,
      "profile_path": "/ejAKOJME1DsvHECLWdQ7dEtXyyc.jpg"
    }
  ]
}
```

amodb 不提供剧集的汇总演职员，也不支持按 `credit_id` 查询。要获取剧集的演员表，请读取 `/tv/{series_id}/credits` 并按 `order` 对 `cast` 排序。

## 在应用中读取演员和幕后人员

| 任务        | 做法                                                 |
| --------- | -------------------------------------------------- |
| 显示导演      | 挑出 `job` 等于 `Director` 的 `crew` 条目。一部电影可以有多位。      |
| 显示主演      | 按 `order` 对 `cast` 排序，取前 10 位。                     |
| 给幕后人员分组   | 按 `department` 分组。一个人有两个职务时会出现两次，所以请按人物 `id` 合并。   |
| 显示剧集演员表   | 读取剧集的演职员，并按 `order` 对 `cast` 排序。                   |
| 列出所有部门和职务 | 读取[类型与查找列表](https://amodb.dev/zh/genres/)中介绍的查找列表。 |

## 错误

| HTTP | status_code | 何时出现                          |
| ---- | ----------- | ----------------------------- |
| 401  | 7           | 密钥缺失或错误。                      |
| 402  | 36          | 套餐周期已结束。                      |
| 404  | 34          | 电影、剧集、季或集不存在，或该路径不提供。         |
| 405  | 37          | 你调用了写入方法。                     |
| 429  | 25          | 超过每分钟请求数。请等待 `Retry-After` 秒。 |

详情见[错误](https://amodb.dev/zh/errors/)和[速率限制](https://amodb.dev/zh/rate-limits/)。

## 实用说明

- 演职员和详情一样缓存 6 小时。新加入的演员可能要这么久才会出现。
- 大型制作可能列出数百位幕后人员。渲染之前请先截取数组的一部分。
- 没有照片的人物，`profile_path` 为 null。列表行用 `w185`，详情视图用 `h632`。
- 电影和电视剧记录见[电影](https://amodb.dev/zh/movies/)和[电视剧](https://amodb.dev/zh/tv-series/)。季和集的记录见[季与集](https://amodb.dev/zh/tv-seasons-episodes/)。

## 常见问题

### 如何获取一部剧集的演员表？

调用 GET /3/tv/{series_id}/credits 并按 order 对 cast 数组排序。季的演职员只覆盖一季，单集演职员则增加 guest_stars。amodb 不提供剧集的汇总演职员。

### 如何找到一部电影的导演？

读取 crew 数组，挑出 job 为 Director 的条目。一部电影可能有多位导演，所以请收集所有匹配项，而不是找到第一个就停下。

### order 字段是什么意思？

order 是演员的署名位置，0 表示署名第一。按 order 对 cast 排序，可以先显示主角。幕后人员条目没有 order。

### 客串演员从哪里来？

只有单集演职员接口会在 crew 旁返回 guest_stars 数组，其 cast 数组为空。季和剧集的演职员不会单独列出客串演员。

## 相关页面

- [人物详情 API](https://amodb.dev/zh/people/): 路径和 JSON 与 TMDB v3 相同的人物详情 API。按 ID 获取演员或幕后人员，含传记、作品列表、外部 ID 和热门列表。
- [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。
- [电视剧 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/actor-api/): 基于 TMDB v3 人物接口的演员 API：获取传记、通过 combined_credits 得到完整作品列表、头像照片和热门榜单，支持 14 种语言。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/credits/