电影预告片 API

电影预告片 API 即 api.amodb.dev 上的 GET /3/movie/{movie_id}/videos。每个视频都有类型、官方标记、语言和发布日期，一遍就能选出官方预告片。剧集返回相同结构，路径和 JSON 与 TMDB v3 一致。

查看套餐阅读快速入门

请求

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"

const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');

响应 200

{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"

获取一部电影的官方预告片

GET /3/movie/{movie_id}/videos 返回关联到一部电影的所有视频。每一项都有 type、official 标记、语言代码、published_at 时间戳，以及标识视频的 site 和 key。保留 type 为 Trailer 且 official 为 true 的条目，就得到了预告片。

你得到的是一份可以自行排序的视频记录列表，而不是视频流。响应给出视频名称及其所在位置，你的页面再根据 site 和 key 构建播放器。电视剧返回同样的结构。季和单集路径返回空列表。

可获取的数据

接口	返回内容
`GET /3/movie/{movie_id}/videos`	一部电影的预告片、先导片、片段、花絮、幕后和 NG 镜头
`GET /3/tv/{tv_id}/videos`	一部剧集的同类列表
`GET /3/tv/{tv_id}/season/{season_number}/videos`	始终返回空的 `results` 列表
`GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos`	始终返回空的 `results` 列表
`GET /3/movie/{movie_id}`，配合 `append_to_response=videos`	一次请求获取详情和视频

每个视频的字段：

字段	类型	用途
`type`	string	视频种类：`Trailer`、`Teaser`、`Clip`、`Featurette`、`Behind the Scenes` 或 `Bloopers`，与视频页相同
`official`	boolean	视频被标记为官方时为 `true`
`iso_639_1`、`iso_3166_1`	string	视频的语言和国家代码
`key`、`site`	string	视频的标识符和托管网站的名称，目前所见每个视频都是 `YouTube`
`size`	integer	垂直分辨率，目前所见每个视频都是 `1080`
`published_at`	string	ISO 8601 时间戳，适合按最新优先排序
`name`、`id`	string	视频标题及其 ID，该 ID 与 `key` 是同一个字符串

三步开始

在定价页选择套餐。每个套餐返回全部数据，所以按每分钟请求数来选。
在账户后台创建密钥。它是 32 位小写十六进制字符。
调用 GET /3/movie/{movie_id}/videos，密钥放在 api_key 或 Authorization: Bearer 请求头中。

请求示例

示例请求《盗梦空间》（ID 27205）的视频，在代码中排序，并打印最佳的一个。排序规则是：先看语言是否匹配，再 Trailer 优先于 Teaser，再官方优先于非官方，最后取最新的 published_at。

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"

const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');

精简响应：42 个视频中的前 2 个。列表包含所有语言。

JSON

{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"
    },
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "35mm Theatrical Trailer #3",
      "key": "cdx31ak4KbQ",
      "site": "YouTube",
      "size": 1080,
      "type": "Trailer",
      "official": false,
      "published_at": "2022-03-07T06:00:19Z",
      "id": "cdx31ak4KbQ"
    }
  ]
}

选择要播放的视频

一部作品常常有多个官方预告片（首发和最终版），旁边还有先导片和片段。请用固定顺序对它们排序，避免预告片位置上出现 NG 镜头集锦。

优先级	筛选	典型用途
1	`Trailer`，官方，语言匹配	要播放的视频
2	`Trailer`，非官方	没有官方版本时的地区版或粉丝上传
3	`Teaser`，官方	上映前的短片
4	`Clip`、`Featurette`	兜底，避免该位置为空
跳过	`Behind the Scenes`、`Bloopers`	放在单独的附加内容列表中

并列时按 published_at 排序。最新优先得到最近的版本，最早优先得到首次发布的版本。

预告片语言

视频通过 iso_639_1 标记语言，一部作品可以有多种语言的预告片。《盗梦空间》有 9 种语言的 42 个视频。amodb 在一个响应中全部返回。language 和 include_video_language 参数对视频接口没有作用，所以请在代码中选择语言。

步骤	怎么做
1	保留 `iso_639_1` 与你的用户匹配的视频，例如 `ru`
2	如果都不匹配，保留 `en`
3	如果仍不匹配，保留其余的

每一步内部像示例中那样，按类型和 official 标记排序。视频语言取决于上传，而不是语言页列出的 14 种界面语言，所以预告片可能是 cs 或 he。

剧集预告片

剧集预告片位于 /3/tv/1396/videos（《绝命毒师》），其中有 9 个预告片。上面的排序函数无需修改即可使用，因为字段没有变化。像 /3/tv/1396/season/1/videos 这样的季和单集路径返回 200 和空的 results 列表，所以请读取剧集的列表。完整的路径列表见视频与预告片。

构建预告片栏

“正在上映”影片的预告片栏需要一次列表调用外加每部作品一次调用：GET /3/movie/now_playing（见热门趋势与列表）加十次视频调用，十部作品共 11 个请求。请把选中的 key 与电影 ID 一起保存。预告片很少变化，所以每隔几小时或作品重新上映时刷新一次已保存的选择。

对比

能力	自己抓取页面	免费层元数据 API	amodb
官方标记	从页面标题猜测	请查阅其文档	每个视频上的 `official` 布尔值
视频类型筛选	解析文本	请查阅其文档	六种 `type` 取值
语言选择	每个页面一种区域设置	请查阅其文档	每个视频上的 `iso_639_1` 和 `iso_3166_1`，在你的代码中过滤
剧集与单集	需要爬取的独立页面	请查阅其文档	剧集使用同一接口，季和单集列表为空
维护	标记变化就会失效	取决于提供方	一种稳定的 JSON 结构
条款	风险由你承担	请查看其条款	付费套餐，见定价

定价

套餐为预付方式。可购买 1、3、6、12 或 24 个月，较长的周期分别享受 0、10、20、30 或 40% 的折扣。不会自动续费。每分钟 20、40 和 120 个请求的套餐都提供本页的所有接口，所以繁忙的预告片栏只取决于速率。没有免费额度，也没有试用。请在定价页比较套餐。

常见问题

如何获取一部电影的官方预告片？

调用 GET /3/movie/{movie_id}/videos，保留 type 为 Trailer 且 official 为 true 的条目，再按 published_at 排序。第一条就是最新的官方预告片。如果没有预告片，则回退到 Teaser。

API 返回视频文件或视频流吗？

不返回。它返回每个视频的元数据：name、type、site、key、size、language 和日期。你可以用 site 和 key 构建播放器链接，或把视频嵌入你自己的页面。海报和剧照来自 img.amodb.dev。

如何获取我所用语言的预告片？

videos 接口会在一个响应中返回所有语言，并忽略 language 和 include_video_language 参数。请在代码中按 iso_639_1 过滤，例如先 ru，再 en，再其余。《盗梦空间》有 9 种语言的视频。

能获取电视剧和单集的预告片吗？

剧集可以：使用 /3/tv/{tv_id}/videos。字段相同，因此你为电影写的排序代码无需修改。季和单集的视频路径返回空的 results 数组，所以请使用剧集的列表。

一次预告片查询用多少次请求？

每部作品一次请求。使用 append_to_response=videos 时，预告片包含在详情调用中，所以详情加预告片仍然只占用你每分钟 20、40 或 120 个请求中的一个。

更新于 2026年10月18日

以 Markdown 查看