# 电影预告片 API

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

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

`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` 是同一个字符串                                                      |

## 三步开始

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

## 请求示例

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

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

```js
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` 标记排序。视频语言取决于上传，而不是[语言](https://amodb.dev/zh/languages/)页列出的 14 种界面语言，所以预告片可能是 `cs` 或 `he`。

## 剧集预告片

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

## 构建预告片栏

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

## 对比

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

## 定价

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

## 常见问题

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

调用 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 个请求中的一个。

## 相关页面

- [视频与预告片 API](https://amodb.dev/zh/videos-trailers/): 兼容 TMDB v3 路径的电影视频 API：列出电影或剧集的预告片、先导预告、片段和花絮，再在你的代码里按类型和语言筛选。
- [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。
- [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 ID 获取剧集的季、电视网和下一集，以及内容分级和观看平台。
- [热门与榜单接口](https://amodb.dev/zh/trending-lists/): 兼容 TMDB v3 路径的热门电影 API：日榜与周榜，以及电影和电视剧的正在上映、热门、高分、即将上映榜单，缓存 30 分钟。
- [语言](https://amodb.dev/zh/languages/): amodb 以 14 种语言提供片名、简介和姓名。在 language 中传入 ru-RU 或 pt-BR 这样的 TMDB 风格标签，其他标签回退到英语。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/movie-trailer-api/