热门和流行榜单缓存多久？

边缘缓存会把热门、流行、正在上映和正在播出的榜单保留 30 分钟，并在各密钥之间共享每个条目。轮询频率高于每 30 分钟一次只会得到同一页，并白白消耗请求。

一个榜单我能读取多少页？

页码范围是 1 到 500，每页 20 条结果，与 TMDB 的限制相同。要更深入地浏览，请使用 discover，它按类型、年份、演员或公司筛选，而不是沿着某一个固定榜单。

哪些榜单接受 region 参数？

now_playing 和 upcoming 接受 region，需为大写两位国家代码，例如 GB，并只保留在该国上映的作品。popular 和 top_rated 也接受它，但只是把 release_date 换成当地日期。电视剧榜单没有 region，airing_today 和 on_the_air 使用 timezone。

可以按类型筛选榜单吗？

这些路径不行。榜单条目带有 genre_ids 供展示。要按类型筛选，请使用带 with_genres 的 discover，并用类型列表接口把 ID 转成名称。

热门电影 API：热门、高分与正在上映榜单

获取热门作品

GET /3/trending/{media_type}/{time_window} 返回人们此刻正在观看或查询内容的排名分页。media_type 为 all、movie、tv 或 person。time_window 为 day 或 week。日榜变化很快，适合今晚栏目。周榜更稳定，适合首页。

示例请求每周电影榜并打印前十部作品。

curl JavaScript Python PHP Go

bashjspyphpgo

curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const chart = await res.json();
for (const [i, m] of chart.results.slice(0, 10).entries()) {
  console.log(i + 1, m.title, m.release_date);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/trending/movie/week",
    params={"language": "en-US", "page": 1},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
for i, m in enumerate(r.json()["results"][:10], start=1):
    print(i, m["title"], m.get("release_date"))

<?php
$url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
$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");
}
$chart = json_decode($body, true);
foreach (array_slice($chart['results'], 0, 10) as $i => $m) {
    echo ($i + 1), ' ', $m['title'], ' ', $m['release_date'] ?? '', PHP_EOL;
}

package main

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

type Chart struct {
	Results []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"results"`
}

func main() {
	url := "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1"
	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 chart Chart
	if err := json.NewDecoder(res.Body).Decode(&chart); err != nil {
		panic(err)
	}
	for i, m := range chart.Results {
		if i == 10 {
			break
		}
		fmt.Println(i+1, m.Title, m.ReleaseDate)
	}
}

参数

media_type路径必填
all、movie、tv 或 person。
time_window路径必填
day 或 week。
api_key查询二选一
你的密钥。使用它，或使用 Authorization: Bearer 请求头。
language查询
en-US 或 ru-RU 这样的 TMDB 标签。提供 14 种基础语言，其他一律回退到英文。
page查询
页码，1 到 500。每页 20 条结果。

响应字段

字段	类型	说明
`page`	integer	你请求的页码。
`results`	array	电影、电视剧或人物对象，排名最高的在前。
`total_pages`、`total_results`	integer	分页总数。热门榜最多报告 500 页和 10000 条结果。
`media_type`	string	每个热门条目上的 `movie`、`tv` 或 `person`。请求 `all` 时请读取它。
`id`	integer	配合电影、电视剧或人物使用。
`title`、`original_title`	string	电影条目。电视剧条目使用 `name` 和 `original_name`。
`release_date`、`first_air_date`	string	电影和电视剧条目的 `YYYY-MM-DD`。
`genre_ids`	array	数字 ID。名称来自类型。
`popularity`、`vote_average`、`vote_count`	number	排名依据和汇总用户评分。
`poster_path`、`backdrop_path`、`profile_path`	string 或 null	拼接到 `https://img.amodb.dev/t/p/{size}`。
`name`、`original_name`、`gender`、`known_for_department`	string 或 integer	人物条目。热门人物条目的 `known_for` 是空数组。

示例响应

JSON

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/7ULXMNvmZSi13zN3EZjz8wbER9B.jpg",
      "genre_ids": [28, 53],
      "id": 1561726,
      "original_language": "en",
      "original_title": "Masterplan",
      "overview": "When a legendary thief sets his sights on the Mona Lisa, he recruits two young strangers to help him before...",
      "popularity": 189.8286,
      "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg",
      "release_date": "2026-10-16",
      "title": "Masterplan",
      "video": false,
      "vote_average": 7.279,
      "vote_count": 61,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg",
      "genre_ids": [878, 9648, 28],
      "id": 1058424,
      "original_language": "ko",
      "original_title": "호프",
      "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to...",
      "popularity": 294.6518,
      "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg",
      "release_date": "2026-07-15",
      "title": "Hope",
      "video": false,
      "vote_average": 6.917,
      "vote_count": 246,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg",
      "genre_ids": [28, 14],
      "id": 1153576,
      "original_language": "en",
      "original_title": "Street Fighter",
      "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun...",
      "popularity": 209.3923,
      "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg",
      "release_date": "2026-10-13",
      "title": "Street Fighter",
      "video": false,
      "vote_average": 6.316,
      "vote_count": 76,
      "media_type": "movie"
    }
  ],
  "total_pages": 500,
  "total_results": 10000
}

响应取自线上 API，并缩减为第 1 页 20 条中的 3 条。较长的 overview 字符串已缩短，排名和计数在每次刷新时都会变化。

电影榜单

电影榜单结构相同：由电影对象组成的分页 results 数组。now_playing 和 upcoming 还会多一个带 minimum 和 maximum 的 dates 对象，即榜单覆盖的上映窗口。四个榜单都接受 language、page 和 region。

方法和路径	返回内容
`GET /movie/now_playing`	在今天前后 `dates` 窗口内上映的电影，外加 `dates`
`GET /movie/popular`	按当前热度排名的电影
`GET /movie/top_rated`	按用户评分排名的电影
`GET /movie/upcoming`	上映日期在未来的电影，外加 `dates`
`GET /movie/latest`	一个电影对象：目录中最新的条目。它不是列表

真实的 dates 对象如下：

JSON

{ "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } }

region 是大写的 ISO 3166-1 代码，例如 DE 或 GB。在 now_playing 和 upcoming 上，它只保留在该国上映的作品，所以榜单只是全球榜单的一小部分。未知代码返回空列表。在 popular 和 top_rated 上，它只是把 release_date 换成当地日期，不改变排名。想知道一部电影在哪里放映，请把 now_playing 与放映时间搭配使用。

电视剧榜单

电视剧榜单返回相同的分页字段。条目用 name、original_name、first_air_date 和 origin_country 代替电影的字段名。四个榜单都接受 language 和 page。

方法和路径	返回内容	额外参数
`GET /tv/airing_today`	今天有一集播出的剧集	`timezone`
`GET /tv/on_the_air`	未来几天内有一集播出的剧集	`timezone`
`GET /tv/popular`	按当前热度排名的剧集	无
`GET /tv/top_rated`	按用户评分排名的剧集	无
`GET /tv/latest`	一个电视剧对象：目录中最新的条目。它不是列表	无

timezone 是 IANA 名称，例如 Europe/Rome。它决定哪个日历日算作今天，所以 airing_today 对 Asia/Tokyo 与对 Pacific/Auckland 返回的集合不同。电视剧榜单没有 region 参数。

人物榜单

GET /person/popular 返回按热度排名的人物分页列表，接受 language 和 page。每个条目有 id、name、original_name、known_for_department、gender、profile_path、popularity 和一个 known_for 数组，其中最多有 3 张电影或电视剧卡片，每张都带 media_type。在人物中打开某个人物。

JSON

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "gender": 1,
      "id": 1247604,
      "known_for_department": "Acting",
      "name": "Agnez Mo",
      "original_name": "Agnez Mo",
      "popularity": 45.8988,
      "profile_path": "/7GuBJxf5szQRCKLk3iG2ztfCo39.jpg",
      "known_for": [
        {
          "adult": false,
          "backdrop_path": "/pF0qkRsrHkdYadPWY9AMeFZfcwk.jpg",
          "first_air_date": "2022-02-03",
          "genre_ids": [10759],
          "id": 108978,
          "name": "Reacher",
          "origin_country": ["US"],
          "original_language": "en",
          "original_name": "Reacher",
          "overview": "Jack Reacher, a veteran military police investigator, has just recently enter...",
          "popularity": 411.841,
          "poster_path": "/f1VCQIG2iCyOookdgOzwtUpwWC0.jpg",
          "vote_average": 8.1,
          "vote_count": 3508,
          "media_type": "tv"
        }
      ]
    }
  ],
  "total_pages": 1001,
  "total_results": 20001
}

amodb 不提供 person/latest 或 changes 数据流。

为每个界面选对榜单

界面	调用	刷新
首页主视觉行	`/trending/all/week`	最多每 30 分钟一次
影院热映标签页	带你的 `region` 的 `/movie/now_playing`	最多每 30 分钟一次
即将上映标签页	带你的 `region` 的 `/movie/upcoming`	最多每 30 分钟一次
今晚电视栏目	带 `timezone` 的 `/tv/airing_today`	最多每 30 分钟一次
历来最爱	`/movie/top_rated`	每天一次就够
人们正在查询的人物	`/trending/person/day`	最多每 30 分钟一次
总体最热门的人物	`/person/popular`	最多每 30 分钟一次

错误

HTTP	status_code	何时出现
401	7	密钥缺失或错误。
402	36	套餐周期已结束。
404	34	路径不存在，例如拼错的榜单名称，或不在上面列表中的 `media_type` 或 `time_window`。
405	37	你对榜单路径使用了写入方法。
429	25	超过了每分钟请求数。请等待 `Retry-After` 秒。
500	11	`page` 超过 500。

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

实用说明

边缘缓存会把热门、流行、正在上映和正在播出的榜单保留 30 分钟，所有密钥共享同一个条目。每 30 分钟运行一次的刷新任务就足够了。
页码范围为 1 到 500。热门榜单报告的 total_results 为 20001，这是上限而不是真实数量。超过第 500 页后，请使用带 sort_by 和筛选条件的发现 API，它能触达榜单永远不会显示的作品。
榜单条目只包含卡片所需的字段。要获取片长、imdb_id 或演职员，请在用户每打开一张卡片时，用 append_to_response 调用电影详情一次。
language 控制标题和简介的语言。没有译文的标题会以原文返回，所以渲染卡片前请检查空字符串。
保存榜单中的 id，而不是位置。排名在每次刷新时都会变化。