人物详情 API
人物接口通过 GET /3/person/{person_id} 按 ID 返回一位演员、导演或幕后人员。JSON 与 TMDB v3 一致:传记、生日、出生地、头像和部门。配套接口返回电影、电视剧及合并的演职员记录、外部 ID、头像图片和热门列表。
获取人物详情
GET / 返回一个人物的核心记录:姓名、传记、生日、出生地、部门、头像和 IMDb ID。ID 是 TMDB 的数字人物 ID,所以汤姆·汉克斯仍是 31,莱昂纳多·迪卡普里奥仍是 6193。台前和幕后的人共用一个 ID 空间。
示例读取汤姆·汉克斯并追加他的合并演职员记录,然后打印姓名、生日、主要部门以及他有多少条表演记录。
curl -sSf "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \
-H "Authorization: Bearer $AMODB_KEY"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);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
$url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits';
$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");
}
$person = json_decode($body, true);
echo $person['name'], ' ', $person['birthday'], ' ', count($person['combined_credits']['cast']), PHP_EOL;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:/。见图片。 |
popularity | number | 热门列表使用的相对分数。 |
adult | boolean | 始终为 false。成人人物永远不会提供。 |
示例响应
GET /,传记已缩短:
{
"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 / | 电影,cast 中有 character 和 order,crew 中有 department 和 job | 无 |
GET / | 剧集,cast 中有 character,crew 中有 department 和 job | 无 |
GET / | 电影和剧集合在一起,每条的 media_type 为 movie 或 tv | 无 |
电影条目带有 title 和 release_date。电视剧条目带有 name 和 first_air_date,电视剧演员条目还有一个 episode_count 键,在当前数据中为 0。条目还带有 credit_id、genre_ids、poster_path、vote_average 和其他列表字段。下面的代码片段按日期对合并演职员记录排序,并打印最新的五条。
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 / | profiles 数组中的头像照片 | 无 |
GET / | 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。头像照片见图片,外部 ID 见按外部 ID 查找。
amodb 不提供人物译文、最新人物记录、带标签图片或变更。请改用 language 参数获取你需要的语言的传记。
错误
| HTTP | status_code | 何时出现 |
|---|---|---|
| 401 | 7 | 密钥缺失或错误。 |
| 402 | 36 | 套餐周期已结束。 |
| 404 | 34 | 没有该 ID 的人物、成人人物,或不提供的路径。 |
| 405 | 37 | 你调用了写入方法。 |
| 429 | 25 | 超过每分钟请求数。请等待 Retry-After 秒。 |
实用说明
- 人物详情和演职员列表缓存 6 小时。热门列表缓存 30 分钟,页码范围为 1 到 500。
- 通过
append_to_response加入combined_credits,而不是再发一次调用。两种方式返回的数据相同。 - 在
movie_credits中,每个cast条目都有order值,即此人在那部电影中的署名位置。电视剧条目没有order,所以请按first_air_date排序。 - 用
known_for_department决定先显示哪个列表:演员先显示cast,导演和编剧先显示crew。 - 在搜索中按姓名查找人物,然后在这里使用其 ID。