人物详情 API

人物接口通过 GET /3/person/{person_id} 按 ID 返回一位演员、导演或幕后人员。JSON 与 TMDB v3 一致:传记、生日、出生地、头像和部门。配套接口返回电影、电视剧及合并的演职员记录、外部 ID、头像图片和热门列表。

更新于 以 Markdown 查看

获取人物详情

GET /3/person/{person_id} 返回一个人物的核心记录:姓名、传记、生日、出生地、部门、头像和 IMDb ID。ID 是 TMDB 的数字人物 ID,所以汤姆·汉克斯仍是 31,莱昂纳多·迪卡普里奥仍是 6193。台前和幕后的人共用一个 ID 空间。

示例读取汤姆·汉克斯并追加他的合并演职员记录,然后打印姓名、生日、主要部门以及他有多少条表演记录。

bashjspyphpgo
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。未知名称会被忽略。

响应字段

字段类型说明
idinteger人物 ID。
namestring显示名称,存在译文时使用所请求的 language。
also_known_asarray其他名称和写法。
biographystring本地化文本,没有译文时为空。
birthday、deathdaystring 或 nullYYYY-MM-DD。在世的人 deathday 为 null。
place_of_birthstring 或 null自由文本。
genderinteger0 未指定,1 女性,2 男性,3 非二元。
known_for_departmentstring主要工作,例如 Acting 或 Directing。
imdb_idstring 或 null形如 nm0000158 的 IMDb 人物 ID。
homepagestring 或 null官方网站。
profile_pathstring 或 null拼接到 https://img.amodb.dev/t/p/{size}。见图片。
popularitynumber热门列表使用的相对分数。
adultboolean始终为 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 和其他列表字段。下面的代码片段按日期对合并演职员记录排序,并打印最新的五条。

JavaScript
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}/imagesprofiles 数组中的头像照片无
GET /person/{person_id}/external_idsimdb_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 参数获取你需要的语言的传记。

错误

HTTPstatus_code何时出现
4017密钥缺失或错误。
40236套餐周期已结束。
40434没有该 ID 的人物、成人人物,或不提供的路径。
40537你调用了写入方法。
42925超过每分钟请求数。请等待 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。