# 系列合集 API > 系列合集把一个系列的电影归在一起，例如三部曲。GET /3/collection/{collection_id} 返回名称、简介、图稿和按上映顺序排列的 parts 电影数组。电影通过 belongs_to_collection 指回所属合集，可双向查找。 ## 接口 `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` 响应: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## 获取合集 `GET /3/collection/{collection_id}` 返回一个系列：它的名称、简介、海报、背景图和 `parts` 数组。每个成员是一份电影摘要，包含制作卡片所需的字段，所以一次调用就能画出整个系列的货架。 示例加载合集 10，即《星球大战》系列电影，并按上映顺序打印其中的电影。 ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```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"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?language=en-US" 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 c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### 参数 | 参数 | 位置 | 必填 | 说明 | | --------------- | -- | --- | ----------------------------------------------------------------- | | `collection_id` | 路径 | 是 | 数字形式的合集 ID，例如 `10`。 | | `api_key` | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。 | | `language` | 查询 | 否 | 提供的 14 种语言之一，例如 `en-US` 或 `fr-FR`。设置每个成员影片的标题和简介所用的语言。默认 `en-US`。 | 合集自身的 `name` 和 `overview` 按存储内容返回，不随 `language` 变化。有些合集的这两项不是英语。 ### 响应字段 | 字段 | 类型 | 说明 | | --------------------------------------------- | -------------- | ------------------------------------------------------------------------------- | | `id` | integer | 合集 ID。 | | `name` | string | 系列名称。 | | `overview` | string | 简短描述。有些合集为空。 | | `poster_path`、`backdrop_path` | string 或 null | 拼接到 `https://img.amodb.dev/t/p/{size}`。见[图片](https://amodb.dev/zh/images-api/)。 | | `parts` | array | 电影摘要，`release_date` 最早的在前。 | | `parts[].id` | integer | 电影 ID。把它传给[电影详情](https://amodb.dev/zh/movies/)。 | | `parts[].title`、`parts[].original_title` | string | 本地化标题和原始标题。 | | `parts[].overview` | string | 本地化的剧情简介。 | | `parts[].release_date` | string | `YYYY-MM-DD`，没有日期的影片为空字符串。这类成员排在最后。 | | `parts[].media_type` | string | 在合集中始终为 `movie`。 | | `parts[].genre_ids` | array | 数字 ID。名称来自[类型](https://amodb.dev/zh/genres/)。 | | `parts[].adult`、`parts[].video` | boolean | `adult` 始终为 `false`，因为不提供成人作品。 | | `parts[].original_language` | string | 两位字母的语言代码。 | | `parts[].popularity` | number | 热度分数。 | | `parts[].poster_path`、`parts[].backdrop_path` | string 或 null | 影片的图稿。 | | `parts[].vote_average`、`parts[].vote_count` | number、integer | 用户评分汇总。 | ### 示例响应 这里显示九个成员中的两个。 ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` 为便于在本页显示，较长的字符串用 `...` 截断。真实响应包含完整文本。 ## 查找一部电影所属的合集 你很少从合集 ID 出发。你是从电影出发的，而[电影详情](https://amodb.dev/zh/movies/)记录会告诉你它属于哪里。`belongs_to_collection` 字段是包含 `id`、`name`、`poster_path` 和 `backdrop_path` 的对象。对于不属于任何系列的电影，例如电影 550，它为 `null`。 ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` 下面的示例用两个请求从一部电影沿着这个链接找到它的系列。 ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## 图稿与搜索 系列的海报和背景图就是合集记录的 `poster_path` 和 `backdrop_path` 字段。请按[图片](https://amodb.dev/zh/images-api/)中的说明用它们拼出文件地址。amodb 不提供 `/collection/{collection_id}/images` 和 `/collection/{collection_id}/translations` 路径，所以合集没有备用海报列表，也没有按语言划分的数据行。成员影片的标题则遵循 `language` 参数，而返回语言数据行的路径见[译文](https://amodb.dev/zh/translations/)。 要按名称查找合集，请使用 `GET /3/search/collection?query=matrix`，详见[搜索](https://amodb.dev/zh/search/)。每条结果包含 `id`、`name`、`overview`、`poster_path`、`backdrop_path`、`original_language`、`original_name` 和 `adult`。 ## 错误 | HTTP | status_code | 何时出现 | | ---- | ----------- | ------------------------------- | | 401 | 7 | 密钥缺失或错误。 | | 402 | 36 | 套餐周期已结束。 | | 404 | 34 | 没有该 ID 的合集，或 ID 不是数字。 | | 405 | 37 | 你对合集路径使用了写入方法。 | | 429 | 25 | 你超过了每分钟请求数。请等待 `Retry-After` 秒。 | 完整列表见[错误](https://amodb.dev/zh/errors/)，套餐限制见[速率限制](https://amodb.dev/zh/rate-limits/)。 ## 实用说明 - 合集只归类电影。一部电影最多有一个 `belongs_to_collection` 对象，所以一部影片对应一个系列。 - 成员按上映顺序到达。日期为空的影片排在最后，请把它们标注为尚无日期。 - 合集记录和其他详情一样在边缘缓存 6 小时，所以一个系列页面可以在这段时间内复用同一个响应。 - 成员只带有摘要字段。用户打开某部影片时，再通过[电影详情](https://amodb.dev/zh/movies/)获取时长、演职员和评分。 - 请用 `parts[].id` 作为影片的键，而不是它在系列中的位置。顺序和日期会随时间修正。 - 显示 `name` 之前，请先确认它是你的显示语言。有些合集的名称是其他语言，而 `language` 不会改变它。 ## 常见问题 ### 如何知道一部电影是否属于某个合集？ 读取电影详情记录上的 belongs_to_collection。它是包含 id、name、poster_path 和 backdrop_path 的对象，电影独立存在时为 null。把这个 id 用在合集路径中。 ### parts 是按上映顺序返回的吗？ 是的。parts 数组按 release_date 从旧到新排列。没有日期的影片 release_date 为空并排在最后，请把它标注为尚无日期。 ### 电视剧有合集吗？ 没有。合集只归类电影。剧集由其季和集来描述，详见电视剧以及季与集页面。 ### 如何按名称搜索合集？ 使用合集搜索路径，例如 /3/search/collection?query=matrix。它返回带有 id、名称和图稿的分页列表。取出 id，再调用合集接口获取 parts。 ## 相关页面 - [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。 - [搜索 API](https://amodb.dev/zh/search/): 路径和 JSON 与 TMDB v3 相同的搜索 API。按文本查找电影、电视剧、人物、系列合集、公司和关键词，支持年份筛选和分页。 - [图片 API 与图片主机](https://amodb.dev/zh/images-api/): 采用 TMDB v3 路径的电影图片 API：列出作品的海报、背景图、标志和剧照，再从 img.amodb.dev 以 10 种尺寸无密钥加载。 - [翻译 API](https://amodb.dev/zh/translations/): 兼容 TMDB v3 路径的翻译 API：一次读取电影、剧集或单集以所有语言存储的标题、简介和宣传语，无需逐个语言请求。 - [发现 API](https://amodb.dev/zh/discover/): 与 TMDB v3 筛选条件相同的 discover API。按类型、演员、公司、关键词、年份、评分、时长和平台列出电影和剧集，并可排序。 - [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。 更新于: 2026-10-18. Source: https://amodb.dev/zh/collections/