# 演员 API > 演员 API 即 TMDB v3 人物接口。用 GET /3/person/{person_id} 获取人物，加 combined_credits 得到完整作品列表，加 images 得到头像照片。热门列表、搜索和 IMDb ID 查找共用一个密钥。 ## 查询演员及其作品列表 `GET /3/person/{person_id}` 返回一个人物的传记、出生信息和头像图片路径。加上 `append_to_response=combined_credits`，同一个响应就会包含他所有的电影和电视剧演职员记录。ID 是 TMDB 使用的数字人物 ID，例如 `31` 对应汤姆·汉克斯。 你会得到人物记录、演员和幕后人员的作品列表、头像照片，以及用于发现的列表。演员、导演和编剧都在同样的接口中，区别在于 `known_for_department`。 ## 可获取的数据 | 接口 | 返回内容 | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `GET /3/person/{person_id}` | `name`、`biography`、`birthday`、`deathday`、`place_of_birth`、`known_for_department`、`profile_path`、`imdb_id` | | `GET /3/person/{person_id}/movie_credits` | `cast` 中的电影角色和 `crew` 中的职务 | | `GET /3/person/{person_id}/tv_credits` | 电视剧的同类信息 | | `GET /3/person/{person_id}/combined_credits` | 电影和电视剧合在一个列表中，用 `media_type` 标记 | | `GET /3/person/{person_id}/images` | 照片的 `profiles` 数组 | | `GET /3/person/popular` | 分页的热门人物列表 | | `GET /3/search/person` | 匹配 `query` 的人物 | ## 三步开始 1. 在[定价](https://amodb.dev/zh/pricing/)页选择套餐。所有套餐返回相同的数据，区别只在于每分钟的请求数。 2. 在账户后台生成密钥。 3. 发送 `GET /3/person/31`，带上 `Authorization: Bearer YOUR_API_KEY`，或在查询字符串中使用 `api_key`。 ## 请求示例 这个调用获取汤姆·汉克斯及其合并演职员记录。Python 示例保留有上映日期的电影角色，按时间从新到旧排序，打印五条，并给出照片 URL。 ```bash curl -s "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```python import os import requests BASE = "https://api.amodb.dev/3" HEADERS = {"Authorization": f"Bearer {os.environ['AMODB_KEY']}"} r = requests.get( f"{BASE}/person/31", params={"language": "en-US", "append_to_response": "combined_credits"}, headers=HEADERS, timeout=10, ) r.raise_for_status() person = r.json() movies = [ c for c in person["combined_credits"]["cast"] if c["media_type"] == "movie" and c.get("release_date") ] movies.sort(key=lambda c: c["release_date"], reverse=True) print(person["name"], person["birthday"], person["known_for_department"]) if person.get("profile_path"): print("Photo:", "https://img.amodb.dev/t/p/w342" + person["profile_path"]) for c in movies[:5]: print(c["release_date"][:4], c["title"], "as", c.get("character") or "n/a") ``` `language=en-US` 的精简响应。`combined_credits` 缩减为 2 条演员记录和 1 条幕后记录，传记也做了缩短。 ```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...", "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", "combined_credits": { "cast": [ { "adult": false, "backdrop_path": "/owUcU7WcM42uPXIVJHglDQceY5R.jpg", "genre_ids": [ 12, 16, 35 ], "id": 1084244, "original_language": "en", "original_title": "Toy Story 5", "overview": "", "popularity": 158.5027, "poster_path": "/sfQtVlIHljToOwYjhe21KPGzZWK.jpg", "release_date": "2026-06-17", "title": "Toy Story 5", "video": false, "vote_average": 8.285, "vote_count": 2649, "media_type": "movie", "credit_id": "65edd5772790bf01634423c9", "character": "Woody (voice)", "order": 0 }, { "adult": false, "backdrop_path": "/1dvOCqKgBcXvfqzVPmAAM5Rv4PP.jpg", "genre_ids": [ 16, 35, 10751 ], "id": 863, "original_language": "en", "original_title": "Toy Story 2", "overview": "", "popularity": 49.6885, "poster_path": "/4rbcp3ng8n1MKHjpeqW0L7Fnpzz.jpg", "release_date": "1999-10-30", "title": "Toy Story 2", "video": false, "vote_average": 7.6, "vote_count": 15484, "media_type": "movie", "credit_id": "5ac0152ec3a368443f034084", "character": "Woody (voice)", "order": 0 } ], "crew": [ { "adult": false, "backdrop_path": "/23GjGDQdMHW5C2UYwSV00fE3FNi.jpg", "first_air_date": "2001-09-09", "genre_ids": [ 18, 10768 ], "id": 4613, "name": "Band of Brothers", "origin_country": [], "original_language": "en", "original_name": "Band of Brothers", "overview": "", "popularity": 63.5427, "poster_path": "/pGzV187ogXzgJrvPRy2YPi29ofH.jpg", "vote_average": 8.608, "vote_count": 4424, "media_type": "tv", "credit_id": "5257765d760ee36aaa522862", "department": "Production", "job": "Executive Producer" } ] } } ``` ## 构建作品列表 一个人可以同时出现在同一部作品的 `cast` 和 `crew` 中，例如既演又导的演员。请把这两个数组当作独立的列表，在你自己的视图中合并。电影行和电视剧行使用不同的字段名，请读取正确的那个。 | 字段 | 所属行 | 含义 | | --------------------------------- | -------- | ------------------------------ | | `media_type` | 合并演职员记录 | `movie` 或 `tv` | | `title` 或 `name` | 电影行或电视剧行 | 显示标题 | | `release_date` 或 `first_air_date` | 电影行或电视剧行 | 排序键，可能为空 | | `character` | 演员 | 角色名 | | `job`、`department` | 幕后人员 | 例如 `Directing` 部门中的 `Director` | | `credit_id` | 两者 | 记录行的 ID | 按日期排序，把没有日期的行放在最后，并以 `id` 和 `media_type` 这一对来去重。电视剧的演员行带有 `episode_count`，但 amodb 在这里返回 `0`，所以不要用它来统计集数。amodb 不提供 `GET /3/credit/{credit_id}` 或 `aggregate_credits`。演员和幕后人员字段的详情见[演职员](https://amodb.dev/zh/credits/)页。 ## 头像照片 `profile_path` 可以拼接到图片主机：`https://img.amodb.dev/t/p/{size}{profile_path}`。列表缩略图用 `w185`，个人主页用 `h632`，下载用 `original`。图片无需密钥，缓存 30 天。 需要多张照片时，调用 `GET /3/person/{person_id}/images`。`profiles` 数组包含 `file_path`、`width`、`height`、`aspect_ratio` 和 `vote_average`，因此你可以挑选评分最高的肖像。尺寸表和 `srcset` 见[图片](https://amodb.dev/zh/images-api/)页。 ## 热门人物、搜索和 ID 查找 - `GET /3/person/popular?page=1` 返回分页列表。页码范围为 1 到 500，列表缓存 30 分钟。 - `GET /3/search/person?query=tom+hanks` 按姓名匹配。缓存 10 分钟。 - `GET /3/find/{external_id}?external_source=imdb_id` 把 IMDb 人物 ID 映射到人物。请读取响应中的 `person_results`。见[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)。 ## 对比 | 能力 | 自己抓取网页 | 免费层元数据 API | amodb | | --------- | ---------- | ---------- | --------------------------- | | 作品列表 | 每条记录抓取一个页面 | 请查阅其文档 | 一次调用的 `combined_credits` | | 演员与幕后人员拆分 | 解析各小节标题 | 请查阅其文档 | `cast` 和 `crew` 数组 | | 照片 | 自己下载并缩放 | 请查阅其文档 | `img.amodb.dev` 上的固定尺寸，无需密钥 | | 姓名搜索 | 操作网站的搜索表单 | 请查阅其文档 | `GET /3/search/person` | | ID 映射 | 按姓名匹配 | 请查阅其文档 | 使用 `imdb_id` 的 `/3/find` | | 语言 | 每个网站一种区域设置 | 请查阅其文档 | 通过 `language` 支持 14 种语言 | ## 定价 预付 1、3、6、12 或 24 个月。周期越长折扣越大，分别为 0、10、20、30 或 40%，套餐不会自动续费。三个套餐分别允许每分钟 20、40 和 120 个请求，每个套餐都能使用所有人物接口。一部电影的演员墙只需一次演职员请求，因为姓名和头像路径都包含在内；一个人物页面加上演职员记录也只需一次请求。请选择与你页面访问量相匹配的速率。没有免费额度。请从[定价](https://amodb.dev/zh/pricing/)开始。 ## 常见问题 ### 如何获取一位演员出演过的所有电影和剧集？ 调用 GET /3/person/{person_id}/combined_credits，或在人物请求中加上 append_to_response=combined_credits。cast 数组包含电影和电视剧中的角色，每条都标有 media_type，因此一次请求就能覆盖完整作品列表。 ### 能按姓名查找演员吗？ 能。带 query 参数调用 GET /3/search/person，会返回匹配的人物及其 ID、姓名和头像路径。搜索结果缓存 10 分钟，因此对热门姓名的重复查询成本很低。 ### 演员照片从哪里来，需要密钥吗？ 每个人物都有 profile_path。把它拼接到 https://img.amodb.dev/t/p/{size} 之后，尺寸可选 w185 或 h632 等。图片请求无需密钥，边缘节点会缓存图片 30 天。 ### 如何把演员与 IMDb 人物 ID 对应起来？ 调用 GET /3/find/{external_id}?external_source=imdb_id，并读取 person_results。人物记录也会返回 imdb_id，因此可以同时保存两个 ID，并在任一方向上查找。 ### 有其他语言的传记吗？ 有，通过 language 参数，支持 14 种语言。存在译文时，姓名会跟随你的语言。如果传记没有译文，人物记录会返回英文文本。 ## 相关页面 - [人物详情 API](https://amodb.dev/zh/people/): 路径和 JSON 与 TMDB v3 相同的人物详情 API。按 ID 获取演员或幕后人员，含传记、作品列表、外部 ID 和热门列表。 - [演职员 API](https://amodb.dev/zh/credits/): 与 TMDB v3 路径和 JSON 相同的演职员 API。获取电影、剧集、季和集的演员与幕后人员，含 order、department 和 job 字段。 - [图片 API 与图片主机](https://amodb.dev/zh/images-api/): 采用 TMDB v3 路径的电影图片 API：列出作品的海报、背景图、标志和剧照，再从 img.amodb.dev 以 10 种尺寸无密钥加载。 - [搜索 API](https://amodb.dev/zh/search/): 路径和 JSON 与 TMDB v3 相同的搜索 API。按文本查找电影、电视剧、人物、系列合集、公司和关键词，支持年份筛选和分页。 - [按外部 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/actor-api/