系列合集 API

系列合集把一个系列的电影归在一起,例如三部曲。GET /3/collection/{collection_id} 返回名称、简介、图稿和按上映顺序排列的 parts 电影数组。电影通过 belongs_to_collection 指回所属合集,可双向查找。

更新于 以 Markdown 查看

获取合集

GET /3/collection/{collection_id} 返回一个系列:它的名称、简介、海报、背景图和 parts 数组。每个成员是一份电影摘要,包含制作卡片所需的字段,所以一次调用就能画出整个系列的货架。

示例加载合集 10,即《星球大战》系列电影,并按上映顺序打印其中的电影。

bashjspyphpgo
curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
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);
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
$url = 'https://api.amodb.dev/3/collection/10?language=en-US';
$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");
}
$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;
}
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 变化。有些合集的这两项不是英语。

响应字段

字段类型说明
idinteger合集 ID。
namestring系列名称。
overviewstring简短描述。有些合集为空。
poster_path、backdrop_pathstring 或 null拼接到 https://img.amodb.dev/t/p/{size}。见图片。
partsarray电影摘要,release_date 最早的在前。
parts[].idinteger电影 ID。把它传给电影详情。
parts[].title、parts[].original_titlestring本地化标题和原始标题。
parts[].overviewstring本地化的剧情简介。
parts[].release_datestringYYYY-MM-DD,没有日期的影片为空字符串。这类成员排在最后。
parts[].media_typestring在合集中始终为 movie。
parts[].genre_idsarray数字 ID。名称来自类型。
parts[].adult、parts[].videobooleanadult 始终为 false,因为不提供成人作品。
parts[].original_languagestring两位字母的语言代码。
parts[].popularitynumber热度分数。
parts[].poster_path、parts[].backdrop_pathstring 或 null影片的图稿。
parts[].vote_average、parts[].vote_countnumber、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 出发。你是从电影出发的,而电影详情记录会告诉你它属于哪里。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"
  }
}

下面的示例用两个请求从一部电影沿着这个链接找到它的系列。

JavaScript
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 字段。请按图片中的说明用它们拼出文件地址。amodb 不提供 /collection/{collection_id}/images 和 /collection/{collection_id}/translations 路径,所以合集没有备用海报列表,也没有按语言划分的数据行。成员影片的标题则遵循 language 参数,而返回语言数据行的路径见译文。

要按名称查找合集,请使用 GET /3/search/collection?query=matrix,详见搜索。每条结果包含 id、name、overview、poster_path、backdrop_path、original_language、original_name 和 adult。

错误

HTTPstatus_code何时出现
4017密钥缺失或错误。
40236套餐周期已结束。
40434没有该 ID 的合集,或 ID 不是数字。
40537你对合集路径使用了写入方法。
42925你超过了每分钟请求数。请等待 Retry-After 秒。

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

实用说明

  • 合集只归类电影。一部电影最多有一个 belongs_to_collection 对象,所以一部影片对应一个系列。
  • 成员按上映顺序到达。日期为空的影片排在最后,请把它们标注为尚无日期。
  • 合集记录和其他详情一样在边缘缓存 6 小时,所以一个系列页面可以在这段时间内复用同一个响应。
  • 成员只带有摘要字段。用户打开某部影片时,再通过电影详情获取时长、演职员和评分。
  • 请用 parts[].id 作为影片的键,而不是它在系列中的位置。顺序和日期会随时间修正。
  • 显示 name 之前,请先确认它是你的显示语言。有些合集的名称是其他语言,而 language 不会改变它。