# 人物详情 API > 人物接口通过 GET /3/person/{person_id} 按 ID 返回一位演员、导演或幕后人员。JSON 与 TMDB v3 一致：传记、生日、出生地、头像和部门。配套接口返回电影、电视剧及合并的演职员记录、外部 ID、头像图片和热门列表。 ## 接口 `GET /3/person/{person_id}` ```bash curl "https://api.amodb.dev/3/person/31?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` 响应: ```json { "adult": false, "also_known_as": [ "Thomas Jeffrey Hanks" ], "biography": "Thomas Jeffrey Hanks (born July 9, 1956) is an American actor and filmmaker. Known for both his comedic and dramatic roles, Hanks is one of the most popular and recognizable film stars worldwide, and is widely regarded as an American cultur...", "birthday": "1956-07-09", "deathday": null, "gender": 2, "homepage": null, "id": 31, "imdb_id": "nm0000158", "known_for_department": "Acting", "name": "Tom Hanks", "place_of_birth": "Concord, California, USA", "popularity": 12.98, "profile_path": "/oFvZoKI6lvU03n4YoNGAll9rkas.jpg" } ``` ## 获取人物详情 `GET /3/person/{person_id}` 返回一个人物的核心记录：姓名、传记、生日、出生地、部门、头像和 IMDb ID。ID 是 TMDB 的数字人物 ID，所以汤姆·汉克斯仍是 `31`，莱昂纳多·迪卡普里奥仍是 `6193`。台前和幕后的人共用一个 ID 空间。 示例读取汤姆·汉克斯并追加他的合并演职员记录，然后打印姓名、生日、主要部门以及他有多少条表演记录。 ```bash curl -sSf "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const person = await res.json(); console.log(person.name, person.birthday, person.known_for_department, person.combined_credits.cast.length); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/person/31", params={"language": "en-US", "append_to_response": "combined_credits"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() person = r.json() print(person["name"], person["birthday"], person["known_for_department"], len(person["combined_credits"]["cast"])) ``` ```php 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"); } $person = json_decode($body, true); echo $person['name'], ' ', $person['birthday'], ' ', count($person['combined_credits']['cast']), PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Person struct { Name string `json:"name"` Birthday string `json:"birthday"` Department string `json:"known_for_department"` PlaceOfBirth string `json:"place_of_birth"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/person/31?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 p Person if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.Name, p.Birthday, p.Department, p.PlaceOfBirth) } ``` ### 参数 | 参数 | 位置 | 必填 | 说明 | | -------------------- | -- | --- | ------------------------------------------------------------------------------------------ | | `person_id` | 路径 | 是 | 数字形式的人物 ID，例如 `31`。 | | `api_key` | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。 | | `language` | 查询 | 否 | `en-US` 或 `ru-RU` 这样的 TMDB 标签。存在译文时，传记以该语言返回。 | | `append_to_response` | 查询 | 否 | 用逗号分隔的列表：`movie_credits`、`tv_credits`、`combined_credits`、`external_ids`、`images`。未知名称会被忽略。 | ### 响应字段 | 字段 | 类型 | 说明 | | ---------------------- | ------------- | ------------------------------------------------------------------------------- | | `id` | integer | 人物 ID。 | | `name` | string | 显示名称，存在译文时使用所请求的 `language`。 | | `also_known_as` | array | 其他名称和写法。 | | `biography` | string | 本地化文本，没有译文时为空。 | | `birthday`、`deathday` | string 或 null | `YYYY-MM-DD`。在世的人 `deathday` 为 null。 | | `place_of_birth` | string 或 null | 自由文本。 | | `gender` | integer | 0 未指定，1 女性，2 男性，3 非二元。 | | `known_for_department` | string | 主要工作，例如 `Acting` 或 `Directing`。 | | `imdb_id` | string 或 null | 形如 `nm0000158` 的 IMDb 人物 ID。 | | `homepage` | string 或 null | 官方网站。 | | `profile_path` | string 或 null | 拼接到 `https://img.amodb.dev/t/p/{size}`。见[图片](https://amodb.dev/zh/images-api/)。 | | `popularity` | number | 热门列表使用的相对分数。 | | `adult` | boolean | 始终为 `false`。成人人物永远不会提供。 | ### 示例响应 `GET /3/person/31?language=en-US`，传记已缩短： ```json { "adult": false, "also_known_as": [ "Thomas Jeffrey Hanks" ], "biography": "Thomas Jeffrey Hanks (born July 9, 1956) is an American actor and filmmaker. Known for both his comedic and dramatic roles, Hanks is one of the most popular...", "birthday": "1956-07-09", "deathday": null, "gender": 2, "homepage": null, "id": 31, "imdb_id": "nm0000158", "known_for_department": "Acting", "name": "Tom Hanks", "place_of_birth": "Concord, California, USA", "popularity": 12.98, "profile_path": "/oFvZoKI6lvU03n4YoNGAll9rkas.jpg" } ``` ## 作品列表接口 三个接口列出一个人参与过的作品。它们都接受 `language`，并返回键 `id`、`cast` 和 `crew`。用 `append_to_response` 追加它们时，会省略 `id` 键。 | 方法和路径 | 返回内容 | 额外参数 | | ------------------------------------------ | ----------------------------------------------------------------- | ---- | | `GET /person/{person_id}/movie_credits` | 电影，`cast` 中有 `character` 和 `order`，`crew` 中有 `department` 和 `job` | 无 | | `GET /person/{person_id}/tv_credits` | 剧集，`cast` 中有 `character`，`crew` 中有 `department` 和 `job` | 无 | | `GET /person/{person_id}/combined_credits` | 电影和剧集合在一起，每条的 `media_type` 为 `movie` 或 `tv` | 无 | 电影条目带有 `title` 和 `release_date`。电视剧条目带有 `name` 和 `first_air_date`，电视剧演员条目还有一个 `episode_count` 键，在当前数据中为 `0`。条目还带有 `credit_id`、`genre_ids`、`poster_path`、`vote_average` 和其他列表字段。下面的代码片段按日期对合并演职员记录排序，并打印最新的五条。 ```js const credits = person.combined_credits; const date = (c) => c.release_date || c.first_air_date || ''; const latest = credits.cast.filter((c) => date(c)).sort((a, b) => date(b).localeCompare(date(a))).slice(0, 5); for (const c of latest) console.log(date(c), c.media_type, c.title || c.name, 'as', c.character); ``` ## 列表与图片 | 方法和路径 | 返回内容 | 额外参数 | | -------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------- | | `GET /person/popular` | 带有 `known_for` 作品的热门人物分页列表 | `language`、`page` | | `GET /person/{person_id}/images` | `profiles` 数组中的头像照片 | 无 | | `GET /person/{person_id}/external_ids` | `imdb_id`、`wikidata_id`、`facebook_id`、`instagram_id`、`tiktok_id`、`twitter_id`、`youtube_id` | 无 | 热门条目包含 `id`、`name`、`original_name`、`known_for_department`、`gender`、`profile_path`、`popularity` 和 `known_for` 数组。页码范围为 1 到 500。头像照片见[图片](https://amodb.dev/zh/images-api/)，外部 ID 见[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)。 amodb 不提供人物译文、最新人物记录、带标签图片或变更。请改用 `language` 参数获取你需要的语言的传记。 ## 错误 | 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 小时。热门列表缓存 30 分钟，页码范围为 1 到 500。 - 通过 `append_to_response` 加入 `combined_credits`，而不是再发一次调用。两种方式返回的数据相同。 - 在 `movie_credits` 中，每个 `cast` 条目都有 `order` 值，即此人在那部电影中的署名位置。电视剧条目没有 `order`，所以请按 `first_air_date` 排序。 - 用 `known_for_department` 决定先显示哪个列表：演员先显示 `cast`，导演和编剧先显示 `crew`。 - 在[搜索](https://amodb.dev/zh/search/)中按姓名查找人物，然后在这里使用其 ID。 ## 常见问题 ### 如何获取一位演员的完整作品列表？ 调用 GET /3/person/{person_id}/combined_credits 即可在一个响应中得到电影和电视剧，或在人物请求中加上 append_to_response=combined_credits。每一项都有 media_type，所以可以把电影和剧集区分开。 ### gender 的取值是什么意思？ 0 表示未指定，1 表示女性，2 表示男性，3 表示非二元。许多记录保持为 0，所以不要把它当作错误，也不要围绕它构建逻辑。 ### 人物头像应该使用哪种尺寸？ 列表用 w185，详情页用 h632，都在 img.amodb.dev 上。头像路径可能为 null，所以请为没有照片的人物准备好占位图。 ### 可以按姓名搜索人物吗？ 可以，用带 query 参数的 GET /3/search/person。它在搜索页中说明，返回的 id 就是这里每个接口使用的 person_id。 ## 相关页面 - [演职员 API](https://amodb.dev/zh/credits/): 与 TMDB v3 路径和 JSON 相同的演职员 API。获取电影、剧集、季和集的演员与幕后人员，含 order、department 和 job 字段。 - [演员 API](https://amodb.dev/zh/actor-api/): 基于 TMDB v3 人物接口的演员 API：获取传记、通过 combined_credits 得到完整作品列表、头像照片和热门榜单，支持 14 种语言。 - [搜索 API](https://amodb.dev/zh/search/): 路径和 JSON 与 TMDB v3 相同的搜索 API。按文本查找电影、电视剧、人物、系列合集、公司和关键词，支持年份筛选和分页。 - [图片 API 与图片主机](https://amodb.dev/zh/images-api/): 采用 TMDB v3 路径的电影图片 API：列出作品的海报、背景图、标志和剧照，再从 img.amodb.dev 以 10 种尺寸无密钥加载。 - [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/): 用 TMDB find 接口按 IMDb、TVDB、Wikidata 或 Kinopoisk ID 查找电影、剧集或人物，并读取外部 ID。 - [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。 更新于: 2026-10-18. Source: https://amodb.dev/zh/people/