为什么 find 返回五个数组？

一个 ID 可能指向电影、人物、剧集、单集或季，所以响应为每种类型各设一个数组。在 amodb 中，只有 movie_results、person_results 和 tv_results 有内容。tv_episode_results 和 tv_season_results 始终为空。

ID 未知时会怎样？

与 TMDB 一样，你会得到状态 200 和五个空数组。读取之前请先确认至少有一个数组有内容。缺少或未知的 external_source 则不同：它返回 400 和 status_code 22。

如何获取我已有作品的 Kinopoisk ID？

调用该电影或剧集的 external_ids 接口。它以字符串形式返回 kinopoisk_id，例如《搏击俱乐部》是 361，amodb 不知道时则为 null。把这个字符串连同 external_source=kinopoisk_id 传给 find，即可反向查找。

能把 wikidata 追加到详情调用吗？

能。在电影或电视剧详情请求中加上 append_to_response=wikidata，Wikidata 数据块就会出现在 wikidata 键下，在同一个请求中到达，无需额外调用。

外部 ID 查找 API：IMDb、Kinopoisk

Q: find 接口接受哪些外部来源？

external_source 接受十二个值，其中七个能解析：imdb_id、tvdb_id、wikidata_id、kinopoisk_id、facebook_id、twitter_id 和 instagram_id。另外五个返回空数组。该值必填、小写且必须精确，例如 external_source=imdb_id。

按外部 ID 查找作品

GET /3/find/{external_id} 接受另一个系统的 ID 并返回匹配的记录。路径中是 ID，external_source 查询参数说明它来自哪个系统。amodb 接受十二种来源，其中七种能解析为记录：imdb_id、tvdb_id、wikidata_id、kinopoisk_id、facebook_id、twitter_id 和 instagram_id。

示例把 IMDb ID tt0137523 映射为 TMDB ID。

curl JavaScript Python PHP Go

bashjspyphpgo

curl -sf "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const found = await res.json();
const movie = found.movie_results[0];
console.log(movie ? `${movie.id} ${movie.title}` : 'no match');

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/find/tt0137523",
    params={"external_source": "imdb_id"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["movie_results"]
print(f"{results[0]['id']} {results[0]['title']}" if results else "no match")

<?php
$url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
$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");
}
$movies = json_decode($body, true)['movie_results'];
echo $movies ? $movies[0]['id'] . ' ' . $movies[0]['title'] : 'no match', PHP_EOL;

package main

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

type Found struct {
	MovieResults []struct {
		ID    int    `json:"id"`
		Title string `json:"title"`
	} `json:"movie_results"`
}

func main() {
	url := "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id"
	req, _ := http.NewRequest("GET", url, 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 f Found
	if err := json.NewDecoder(res.Body).Decode(&f); err != nil {
		panic(err)
	}
	if len(f.MovieResults) == 0 {
		fmt.Println("no match")
		return
	}
	fmt.Println(f.MovieResults[0].ID, f.MovieResults[0].Title)
}

参数

external_id路径必填
另一个系统中的 ID，例如 tt0137523。
external_source查询必填
imdb_id、tvdb_id、wikidata_id、kinopoisk_id、facebook_id、twitter_id、instagram_id 之一。另有五个也被接受但不返回任何内容：freebase_mid、freebase_id、tvrage_id、tiktok_id、youtube_id。
language查询
14 种语言之一，例如 en 或 ru-RU。其他值回退到 en。
api_key查询二选一
你的密钥。使用它，或使用 Authorization: Bearer 请求头。

缺少 external_source，或它不在列表中，会返回 400 和 status_code 22。该值必须是小写。

响应字段

字段	类型	说明
`movie_results`	array	与搜索结果字段相同的电影记录，另有设为 `movie` 的 `media_type`。
`person_results`	array	与该 ID 匹配的人物。每项的 `known_for` 为空数组，`media_type` 设为 `person`。
`tv_results`	array	电视剧记录，`media_type` 设为 `tv`。
`tv_episode_results`	array	始终为空。
`tv_season_results`	array	始终为空。

示例响应

JSON

{
  "movie_results": [
    {
      "adult": false,
      "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg",
      "genre_ids": [18, 53],
      "id": 550,
      "original_language": "en",
      "original_title": "Fight Club",
      "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...",
      "popularity": 39.0054,
      "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg",
      "release_date": "1999-10-15",
      "title": "Fight Club",
      "video": false,
      "vote_average": 8.437,
      "vote_count": 33039,
      "media_type": "movie"
    }
  ],
  "person_results": [],
  "tv_results": [],
  "tv_episode_results": [],
  "tv_season_results": []
}

简介已截断。

哪种来源能找到什么

`external_source`	ID 的样子	示例	通常的结果数组
`imdb_id`	作品为 `tt` 加数字，人物为 `nm` 加数字	`tt0137523`、`nm0000093`（布拉德·皮特）	`movie_results`、`tv_results` 或 `person_results`
`tvdb_id`	数字	`81189`（《绝命毒师》）	`tv_results`
`wikidata_id`	`Q` 加数字	`Q190050`（《搏击俱乐部》）、`Q1079`（《绝命毒师》）、`Q35332`（布拉德·皮特）	`movie_results`、`tv_results` 或 `person_results`
`kinopoisk_id`	数字	`361`（《搏击俱乐部》）、`404900`（《绝命毒师》）	`movie_results` 或 `tv_results`
`facebook_id`、`twitter_id`、`instagram_id`	账号名	`FightClub`	取决于账号

同一个账号名可能匹配多个作品。例如 instagram_id=breakingbad 会返回这部剧集和电影 El Camino，所以请读取每一个数组。

curl

curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \
  -H "Authorization: Bearer $AMODB_KEY"

已知作品的外部 ID

反向查询是一组 external_ids 接口。它们为你已有的记录返回其他系统所使用的 ID。

方法和路径	返回内容	参数
`GET /movie/{movie_id}/external_ids`	`imdb_id`、`wikidata_id`、`facebook_id`、`instagram_id`、`twitter_id`、`kinopoisk_id`	`movie_id`
`GET /tv/{tv_id}/external_ids`	同上，另加 `freebase_mid`、`freebase_id`、`tvdb_id`、`tvrage_id`	`tv_id`
`GET /person/{person_id}/external_ids`	`imdb_id`、`wikidata_id`、`facebook_id`、`instagram_id`、`tiktok_id`、`twitter_id`、`youtube_id`	`person_id`

作品没有的 ID 会返回 null。kinopoisk_id 是字符串，只有在 amodb 知道时才会出现在电影或剧集上。/3/movie/550/external_ids 的真实返回：

JSON

{
  "id": 550,
  "imdb_id": "tt0137523",
  "wikidata_id": "Q190050",
  "facebook_id": "FightClub",
  "instagram_id": null,
  "twitter_id": null,
  "kinopoisk_id": "361"
}

/3/tv/1396/external_ids 的真实返回：

JSON

{
  "id": 1396,
  "imdb_id": "tt0903747",
  "freebase_mid": null,
  "freebase_id": null,
  "tvdb_id": 81189,
  "tvrage_id": null,
  "wikidata_id": "Q1079",
  "facebook_id": "BreakingBad",
  "instagram_id": "breakingbad",
  "twitter_id": "BreakingBad",
  "kinopoisk_id": "404900"
}

季和集的 external_ids 接口存在，但其中所有 ID 目前都是 null，所以请跳过它们。

Wikidata 事实

GET /3/movie/{movie_id}/wikidata 和 GET /3/tv/{tv_id}/wikidata 返回作品的 Wikidata ID 及相关事实：金额、系列中的前后作品、维基百科页面、奖项和地点。每个键始终存在。未知的事实，单个值为 null，列表为 []。

方法和路径	返回内容	参数
`GET /movie/{movie_id}/wikidata`	Wikidata ID 和事实	`movie_id`、`language`
`GET /tv/{tv_id}/wikidata`	Wikidata ID 和事实	`tv_id`、`language`
`append_to_response=wikidata`	`wikidata` 下的同一数据块，带有其 `id`	加在详情调用上

这是《搏击俱乐部》（电影 550）的返回内容，已缩减到便于阅读的大小：

JSON

{
  "id": 550,
  "wikidata_id": "Q190050",
  "budget": {
    "value": 63000000,
    "currency": "USD"
  },
  "box_office": {
    "value": 101209702,
    "currency": "USD",
    "worldwide": true
  },
  "follows": null,
  "followed_by": null,
  "sitelinks": {
    "en": "Fight Club",
    "ru": "Бойцовский клуб (фильм)",
    "uk": "Бійцівський клуб (фільм)"
  },
  "awards": [
    {
      "wikidata_id": "Q28044798",
      "label": "Empire Awards, UK for best british actress"
    },
    {
      "wikidata_id": "Q943908",
      "label": "Jupiter Award",
      "year": 2000
    }
  ],
  "nominations": [
    {
      "wikidata_id": "Q488645",
      "label": "Academy Award for Best Sound Editing",
      "year": 2000
    }
  ],
  "based_on": [
    {
      "wikidata_id": "Q837283",
      "label": "Fight Club",
      "author": {
        "wikidata_id": "Q268181",
        "label": "Chuck Palahniuk"
      }
    }
  ],
  "filming_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "narrative_locations": [
    {
      "wikidata_id": "Q65",
      "label": "Los Angeles"
    }
  ],
  "original_broadcasters": []
}

sitelinks 对象有 14 项，awards 有 5 项。这里两者都已截断。

字段	类型	说明
`id`	integer	作品的 TMDB ID。使用 `append_to_response` 时它依然保留。
`wikidata_id`	string 或 null	形如 `Q190050` 的 Wikidata 条目。
`budget`	object 或 null	`value` 是取整后的整数，`currency` 是 ISO 代码或 `null`。
`box_office`	object 或 null	与 `budget` 相同，另有设为 `true` 或 `false` 的 `worldwide`。
`follows`、`followed_by`	object 或 null	系列电影中的前一部和后一部作品，以链接形式给出。
`sitelinks`	object	把语言代码映射到维基百科页面标题。键是提供的 14 种语言。没有时为 `{}`。
`awards`、`nominations`	array	带有可选 `year` 的链接。
`based_on`	array	原著作品，含 `wikidata_id`、`label` 和一个 `author` 对象或 `null`。
`filming_locations`、`narrative_locations`、`original_broadcasters`	array	链接。《绝命毒师》的 `original_broadcasters` 中有 AMC。

链接包含 wikidata_id、label，当该条目是目录中的作品时，还有 tmdb_id 和 media_type。对于《黑客帝国：重装上阵》（电影 604），前后作品是指向电影 603 和 605 的链接：

JSON

{
  "follows": {
    "wikidata_id": "Q83495",
    "label": "The Matrix",
    "tmdb_id": 603,
    "media_type": "movie"
  },
  "followed_by": {
    "wikidata_id": "Q207536",
    "label": "The Matrix Revolutions",
    "tmdb_id": 605,
    "media_type": "movie"
  }
}

每个 label 以请求的 language 返回，找不到时回退到英语。使用 language=ru 时，上面的作者显示为 Чак Паланик。

错误

错误使用 TMDB 的响应体，例如 {"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}。

HTTP	status_code	何时出现
400	22	`external_source` 缺失、不是小写或不在列表中。
401	7	密钥缺失或错误。
402	36	套餐周期已结束。
404	34	`wikidata` 路径中的作品 ID 不存在。
429	25	超过每分钟请求数。请等待 `Retry-After` 秒。

find 上未知的外部 ID 不算错误：预计五个数组都为空。external_ids 接口对未知 ID 同样不返回 404，而是返回 200，所有 ID 都是 null。见错误和认证。

实用说明

第一次解析出外部 ID 时就保存 TMDB ID。之后的调用可以跳过 find 直接走详情路径，每部作品省下一个请求。
始终检查你想要的数组是否有内容。对同一个 ID，find 可能同时返回多个数组。
详情和外部 ID 在边缘缓存 6 小时。在这段时间内重复查询会返回已存储的结果。
wikidata_id 可以双向使用：传给 find 得到作品，或从 external_ids 读取后用于外链。
想把 OMDb 风格的 IMDb 查询迁移过来，见 OMDb 接口。解析出作品之后要获取评分，见评分。