# 电影详情 API > 电影详情接口按 ID 返回一部电影（GET /3/movie/{movie_id}）。JSON 与 TMDB v3 一致，现有客户端只需换基础 URL。用 append_to_response 一次请求加入演职员、视频、图片，以及评分、情绪等扩展。 ## 接口 `GET /3/movie/{movie_id}` ```bash curl "https://api.amodb.dev/3/movie/550?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` 响应: ```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 new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...", "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" }, { "id": 711, "logo_path": "/tEiIH5QesdheJmDAqQwvtN60727.png", "name": "Fox 2000 Pictures", "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": 33042 } ``` ## 获取电影详情 `GET /3/movie/{movie_id}` 返回一部电影的核心记录：标题、简介、时长、类型、上映日期、预算、收入、制作公司和图片路径。ID 就是 TMDB 使用的数字 ID，所以你已经存为 `550` 的电影在这里仍是这个 ID。 下面的示例以英语请求这部电影，并在同一次调用中追加它的评分。 ```bash curl -s "https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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); ``` ```python 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 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; ``` ```go 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 个子资源，用逗号分隔，合并进响应。 | ### 响应字段 | 字段 | 类型 | 说明 | | ----------------------------- | -------------- | ------------------------------------------------------------------------------------- | | `id` | integer | 电影 ID。 | | `imdb_id` | string 或 null | 形如 `tt0137523` 的 IMDb ID。 | | `title`、`original_title` | string | 本地化标题和原始标题。 | | `original_language` | string | 形如 `en` 的语言代码。 | | `overview`、`tagline` | string | 本地化文本，没有译文时为空。 | | `homepage` | string | 官方网站，未知时为空。 | | `release_date` | string | `YYYY-MM-DD`，未知时为空。 | | `status` | string | 上映状态，例如 `Released` 或 `In Production`。 | | `runtime` | integer | 分钟。 | | `budget`、`revenue` | integer | 美元，未知时为 `0`。 | | `genres` | array | 带有 `id` 和 `name` 的对象。 | | `belongs_to_collection` | object 或 null | `id`、`name`、`poster_path`、`backdrop_path`。见[系列合集](https://amodb.dev/zh/collections/)。 | | `production_companies` | array | `id`、`logo_path`、`name`、`origin_country`。 | | `production_countries` | array | `iso_3166_1`、`name`。 | | `spoken_languages` | array | `english_name`、`iso_639_1`、`name`。 | | `origin_country` | array | 形如 `US` 的国家代码。 | | `poster_path`、`backdrop_path` | string 或 null | 拼接到 `https://img.amodb.dev/t/p/{size}`。见[图片](https://amodb.dev/zh/images-api/)。 | | `popularity` | number | 热门列表使用的相对分数。 | | `vote_average`、`vote_count` | number、integer | 用户评分汇总。 | | `adult`、`video` | boolean | 二者都是 `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`，详见[评分](https://amodb.dev/zh/ratings/)。 ## 用 append_to_response 组合数据 一次调用可以替代六次。列出你需要的子资源，每一个都会出现在各自的键下。标准的 TMDB 取值都可用：`credits`、`videos`、`images`、`keywords`、`translations`、`external_ids`、`release_dates`、`alternative_titles`、`recommendations`、`similar`、`reviews`、`lists` 和 `watch/providers`。amodb 另外增加了五个。 | 取值 | 增加 | 详情 | | ------------- | ---------------------------------------------------- | ------------------------------------------------------ | | `ratings` | IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 的评分 | [评分](https://amodb.dev/zh/ratings/) | | `moods` | 情绪指数 | [情绪指数](https://amodb.dev/zh/moods/) | | `soundtracks` | 电影中出现的曲目 | [原声配乐](https://amodb.dev/zh/soundtracks/) | | `wikidata` | Wikidata ID、预算、票房、奖项、拍摄地点 | [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/) | | `showtimes` | 已知的影院放映场次 | [放映场次](https://amodb.dev/zh/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}/recommendations` | 20 部推荐电影的列表 | 无 | | `GET /movie/{movie_id}/similar` | 20 部相似电影的列表 | 无 | | `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 有各自的页面：[演职员](https://amodb.dev/zh/credits/)、[图片](https://amodb.dev/zh/images-api/)、[视频与预告片](https://amodb.dev/zh/videos-trailers/)、[译文](https://amodb.dev/zh/translations/)、[关键词](https://amodb.dev/zh/keywords/)和[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)。amodb 不提供 TMDB 的 `changes` 路径。 ## 错误 错误使用 TMDB 的响应体，例如 `{"success": false, "status_code": 34, "status_message": "The resource you requested could not be found."}`。 | HTTP | status_code | 何时出现 | | ---- | ----------- | ------------------------------- | | 401 | 7 | 密钥缺失或错误。 | | 402 | 36 | 套餐周期已结束。 | | 404 | 34 | 没有该 ID 的电影、不提供的路径，或成人作品。 | | 405 | 37 | 你调用了给电影评分这类写入方法。 | | 429 | 25 | 你超过了每分钟请求数。请等待 `Retry-After` 秒。 | 完整列表见[错误](https://amodb.dev/zh/errors/)页，各套餐的限制见[速率限制](https://amodb.dev/zh/rate-limits/)。 ## 实用说明 - 请把 `id` 和 `imdb_id` 一起保存。任何一个都可以通过[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)再次找到这部电影。 - 请求你要显示的语言。当该语言没有译文时，文本字段可能为空，所以请检查空字符串，需要兜底时再用 `en-US` 重新请求。 - 在你这一侧把详情缓存几个小时。服务器缓存本来就保存 6 小时，所以更短的客户端缓存没有任何收益。 - 要列出电影而不是读取单部电影，见[搜索](https://amodb.dev/zh/search/)、[发现](https://amodb.dev/zh/discover/)和[热门趋势与列表](https://amodb.dev/zh/trending-lists/)。 ## 常见问题 ### 我需要修改 TMDB 客户端代码吗？ 对于 amodb 提供的路径，不需要。路径、查询参数和 JSON 字段与 TMDB v3 相同。把基础 URL 改为 https://api.amodb.dev/3，并在 api_key 或 Bearer 请求头中使用你的 amodb 密钥。 ### append_to_response 最多能合并多少个子请求？ 用逗号分隔的列表最多 20 个值，与 TMDB 相同。整个调用是一次 HTTP 请求，所以只占你每分钟请求数限制中的一次。未知的名称会被忽略且不报错。 ### 省略 language 参数时使用哪种语言？ 英语（en-US）。language 参数接受 ru-RU 或 pt-BR 这样的 TMDB 标签。只提供 14 种基础语言，其他任何标签都会回退到英语。 ### 支持给电影评分这类 TMDB 写入方法吗？ 不支持。账户、会话、评分和列表的写入方法返回 405，TMDB 错误响应体中的 status_code 为 37。作品、人物、列表和搜索的读取路径均已提供。个别 TMDB 路径（例如 changes）不提供。 ### 数据有多新？ 电影详情缓存 6 小时，最新电影接口缓存 10 分钟。一条记录的变更最多可能需要 6 小时才会在详情调用中显示。 ## 相关页面 - [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 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 种尺寸无密钥加载。 - [电影与电视剧评分](https://amodb.dev/zh/ratings/): 一次调用返回作品的 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 评分，来源未知时为 null。 - [热门与榜单接口](https://amodb.dev/zh/trending-lists/): 兼容 TMDB v3 路径的热门电影 API：日榜与周榜，以及电影和电视剧的正在上映、热门、高分、即将上映榜单，缓存 30 分钟。 - [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。 更新于: 2026-10-19. Source: https://amodb.dev/zh/movies/