电影详情 API

电影详情接口按 ID 返回一部电影(GET /3/movie/{movie_id})。JSON 与 TMDB v3 一致,现有客户端只需换基础 URL。用 append_to_response 一次请求加入演职员、视频、图片,以及评分、情绪等扩展。

更新于 以 Markdown 查看

获取电影详情

GET /3/movie/{movie_id} 返回一部电影的核心记录:标题、简介、时长、类型、上映日期、预算、收入、制作公司和图片路径。ID 就是 TMDB 使用的数字 ID,所以你已经存为 550 的电影在这里仍是这个 ID。

下面的示例以英语请求这部电影,并在同一次调用中追加它的评分。

bashjspyphpgo
curl -s "https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
const url = 'https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const movie = await res.json();
console.log(movie.title, movie.runtime, movie.ratings.imdb?.value);
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550",
    params={"language": "en-US", "append_to_response": "ratings"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
movie = r.json()
imdb = movie["ratings"]["imdb"]
print(movie["title"], movie["runtime"], imdb and imdb["value"])
<?php
$url = 'https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings';
$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");
}
$movie = json_decode($body, true);
echo $movie['title'], ' ', $movie['runtime'], ' ', $movie['ratings']['imdb']['value'] ?? 'n/a', PHP_EOL;
package main

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

type Movie struct {
	Title   string `json:"title"`
	Runtime int    `json:"runtime"`
}

func main() {
	url := "https://api.amodb.dev/3/movie/550?language=en-US"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var m Movie
	json.NewDecoder(res.Body).Decode(&m)
	fmt.Println(m.Title, m.Runtime)
}

参数

  • movie_id路径必填
    数字形式的电影 ID,例如 550。
  • api_key查询二选一
    你的密钥。使用它,或使用 Authorization: Bearer 请求头。
  • language查询
    en-US、ru-RU 或 pt-BR 这样的 TMDB 标签。提供 14 种基础语言。默认 en-US。
  • append_to_response查询
    最多 20 个子资源,用逗号分隔,合并进响应。

响应字段

字段类型说明
idinteger电影 ID。
imdb_idstring 或 null形如 tt0137523 的 IMDb ID。
title、original_titlestring本地化标题和原始标题。
original_languagestring形如 en 的语言代码。
overview、taglinestring本地化文本,没有译文时为空。
homepagestring官方网站,未知时为空。
release_datestringYYYY-MM-DD,未知时为空。
statusstring上映状态,例如 Released 或 In Production。
runtimeinteger分钟。
budget、revenueinteger美元,未知时为 0。
genresarray带有 id 和 name 的对象。
belongs_to_collectionobject 或 nullid、name、poster_path、backdrop_path。见系列合集。
production_companiesarrayid、logo_path、name、origin_country。
production_countriesarrayiso_3166_1、name。
spoken_languagesarrayenglish_name、iso_639_1、name。
origin_countryarray形如 US 的国家代码。
poster_path、backdrop_pathstring 或 null拼接到 https://img.amodb.dev/t/p/{size}。见图片。
popularitynumber热门列表使用的相对分数。
vote_average、vote_countnumber、integer用户评分汇总。
adult、videoboolean二者都是 false。成人作品永远不会提供。

示例响应

GET /3/movie/550?language=en-US&append_to_response=ratings,较长的数组和文本已缩短:

JSON
{
  "adult": false,
  "backdrop_path": "/b9HyPoxwxjxkWEUL5ErZdhApQe2.jpg",
  "belongs_to_collection": null,
  "budget": 63000000,
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 53,
      "name": "Thriller"
    }
  ],
  "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
  "id": 550,
  "imdb_id": "tt0137523",
  "origin_country": [
    "US",
    "DE"
  ],
  "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",
  "production_companies": [
    {
      "id": 25,
      "logo_path": "/nM2MfoMqzJQRiSynsDabOtFKetD.png",
      "name": "20th Century Fox",
      "origin_country": "US"
    },
    {
      "id": 508,
      "logo_path": "/4sGWXoboEkWPphI6es6rTmqkCBh.png",
      "name": "Regency Enterprises",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    },
    {
      "iso_3166_1": "DE",
      "name": "Germany"
    }
  ],
  "release_date": "1999-10-15",
  "revenue": 101209702,
  "runtime": 139,
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    }
  ],
  "status": "Released",
  "tagline": "Mischief. Mayhem. Soap.",
  "title": "Fight Club",
  "video": false,
  "vote_average": 8.437,
  "vote_count": 33039,
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2669989
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 67,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 81,
      "votes": null
    },
    "tmdb": {
      "value": 8.437,
      "votes": 33039
    }
  }
}

ratings 数据块来自 append_to_response。每个来源是 {value, votes} 对象或 null,详见评分。

用 append_to_response 组合数据

一次调用可以替代六次。列出你需要的子资源,每一个都会出现在各自的键下。标准的 TMDB 取值都可用:credits、videos、images、keywords、translations、external_ids、release_dates、alternative_titles、recommendations、similar、reviews、lists 和 watch/providers。amodb 另外增加了五个。

取值增加详情
ratingsIMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 的评分评分
moods情绪指数情绪指数
soundtracks电影中出现的曲目原声配乐
wikidataWikidata ID、预算、票房、奖项、拍摄地点按外部 ID 查找
showtimes已知的影院放映场次放映场次

每个追加的数据块都算作同一次 HTTP 请求的一部分。追加了十个值的请求仍然只占用你每分钟 20、40 或 120 个请求中的一个。追加的 ratings、moods 和 soundtracks 数据块省略了独立路径所返回的 id 键。

相关的电影接口

下面所有路径共用基础地址 https://api.amodb.dev/3 和 language 参数。

方法和路径返回内容额外参数
GET /movie/{movie_id}/alternative_titles{id, titles},通常为空数组无
GET /movie/{movie_id}/release_dates各国的上映日期和分级无
GET /movie/{movie_id}/recommendations20 部推荐电影的列表无
GET /movie/{movie_id}/similar20 部相似电影的列表无
GET /movie/{movie_id}/reviews大多数作品的 results 为空无
GET /movie/{movie_id}/lists包含该电影的公开列表page
GET /movie/{movie_id}/watch/providers各国的流媒体和租赁平台无
GET /movie/latest最新添加的电影记录无

推荐和相似列表始终返回第 1 页的 20 项。lists 响应用 page 分页,每页 20 个列表。API 其他位置的分页列表,page 取 1 到 500。

演职员、图片、视频、译文、关键词和外部 ID 有各自的页面:演职员、图片、视频与预告片、译文、关键词和按外部 ID 查找。amodb 不提供 TMDB 的 changes 路径。

错误

错误使用 TMDB 的响应体,例如 {"success": false, "status_code": 34, "status_message": "The resource you requested could not be found."}。

HTTPstatus_code何时出现
4017密钥缺失或错误。
40236套餐周期已结束。
40434没有该 ID 的电影、不提供的路径,或成人作品。
40537你调用了给电影评分这类写入方法。
42925你超过了每分钟请求数。请等待 Retry-After 秒。

完整列表见错误页,各套餐的限制见速率限制。

实用说明

  • 请把 id 和 imdb_id 一起保存。任何一个都可以通过按外部 ID 查找再次找到这部电影。
  • 请求你要显示的语言。当该语言没有译文时,文本字段可能为空,所以请检查空字符串,需要兜底时再用 en-US 重新请求。
  • 在你这一侧把详情缓存几个小时。服务器缓存本来就保存 6 小时,所以更短的客户端缓存没有任何收益。
  • 要列出电影而不是读取单部电影,见搜索、发现和热门趋势与列表。