# 类型与查找列表

> 类型和查找接口返回只需加载一次的小型参考列表：14 种语言的电影和电视剧类型 ID 与名称，以及国家、语言、幕后职务、年龄分级和流媒体平台。它们使用 TMDB v3 的路径和结构，无需分页，很少变化，可缓存一天。

## 接口

`GET /3/genre/movie/list`

```bash
curl "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

响应:

```json
{
  "genres": [
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 16,
      "name": "Animation"
    }
  ]
}
```

## 获取电影类型列表

`GET /3/genre/movie/list` 把每个电影类型返回为一个 `id` 和一个 `name`。这些 ID 就是列表条目中 `genre_ids` 携带的数字，也是[发现](https://amodb.dev/zh/discover/)中 `with_genres` 所需的值。名称遵循 `language` 参数。

示例加载列表并构建 ID 到名称的映射，这是大多数应用首先需要的东西。

```bash
curl -s "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const url = 'https://api.amodb.dev/3/genre/movie/list?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 { genres } = await res.json();
const names = new Map(genres.map((g) => [g.id, g.name]));
console.log(names.get(878), names.size);
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/genre/movie/list",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
names = {g["id"]: g["name"] for g in r.json()["genres"]}
print(names[878], len(names))
```

```php
<?php
$url = 'https://api.amodb.dev/3/genre/movie/list?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");
}
$names = [];
foreach (json_decode($body, true)['genres'] as $g) {
    $names[$g['id']] = $g['name'];
}
echo $names[878], ' ', count($names), PHP_EOL;
```

```go
package main

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

type Genres struct {
	Genres []struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"genres"`
}

func main() {
	url := "https://api.amodb.dev/3/genre/movie/list?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 g Genres
	if err := json.NewDecoder(res.Body).Decode(&g); err != nil {
		panic(err)
	}
	names := map[int]string{}
	for _, x := range g.Genres {
		names[x.ID] = x.Name
	}
	fmt.Println(names[878], len(names))
}
```

### 参数

| 参数         | 位置 | 必填  | 说明                                                         |
| ---------- | -- | --- | ---------------------------------------------------------- |
| `api_key`  | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。                  |
| `language` | 查询 | 否   | `en-US`、`ru-RU` 或 `pt-BR` 这样的 TMDB 标签。名称以该语言返回。默认 `en-US`。 |

### 响应字段

| 字段              | 类型      | 说明               |
| --------------- | ------- | ---------------- |
| `genres`        | array   | 一个响应中包含整个列表，不分页。 |
| `genres[].id`   | integer | 稳定的类型 ID。        |
| `genres[].name` | string  | 所请求语言的类型名称。      |

### 示例响应

```json
{
  "genres": [
    { "id": 12, "name": "Adventure" },
    { "id": 14, "name": "Fantasy" },
    { "id": 16, "name": "Animation" },
    { "id": 18, "name": "Drama" }
  ]
}
```

响应包含 27 个类型，按 ID 排序。这里只保留前 4 个。

## 类型 ID

两个类型路径都返回这 27 个类型，按 ID 排序。下面的名称是英文名。其他语言返回相同的 ID 和翻译后的名称。

| ID    | 名称                 |
| ----- | ------------------ |
| 12    | Adventure          |
| 14    | Fantasy            |
| 16    | Animation          |
| 18    | Drama              |
| 27    | Horror             |
| 28    | Action             |
| 35    | Comedy             |
| 36    | History            |
| 37    | Western            |
| 53    | Thriller           |
| 80    | Crime              |
| 99    | Documentary        |
| 878   | Science Fiction    |
| 9648  | Mystery            |
| 10402 | Music              |
| 10749 | Romance            |
| 10751 | Family             |
| 10752 | War                |
| 10759 | Action & Adventure |
| 10762 | Kids               |
| 10763 | News               |
| 10764 | Reality            |
| 10765 | Sci-Fi & Fantasy   |
| 10766 | Soap               |
| 10767 | Talk               |
| 10768 | War & Politics     |
| 10770 | TV Movie           |

## 电视剧类型列表

`GET /3/genre/tv/list` 接受同样的 `language` 参数并返回完全相同的列表，所以一份 ID 到名称的映射就能覆盖电影和电视剧。在列表数据中，ID `10759` 以及 `10762` 到 `10768` 只出现在电视剧条目上，而 `28`、`12` 和 `878` 这样的 ID 出现在电影条目上。在[发现](https://amodb.dev/zh/discover/)中筛选电视剧时，请使用电视剧的 ID，例如科幻与奇幻的 `10765`。

## 查找列表

这些路径返回用于表单、筛选器和设置界面的参考数据。全部需要密钥，都不接受 `page`。

| 方法和路径                                     | 参数                        | 每一项或结构                                                      |
| ----------------------------------------- | ------------------------- | ----------------------------------------------------------- |
| `GET /configuration/countries`            | 无                         | `{ iso_3166_1, english_name, native_name }` 数组              |
| `GET /configuration/languages`            | 无                         | `{ iso_639_1, english_name, name }` 数组                      |
| `GET /configuration/primary_translations` | 无                         | 由 14 个 `ru-RU` 这样的字符串组成的数组                                  |
| `GET /configuration/jobs`                 | 无                         | `{ department, jobs }` 数组，其中 `jobs` 列出职务名称                  |
| `GET /certification/movie/list`           | 无                         | 以国家代码为键的 `{ certifications }`，共 10 个国家                      |
| `GET /certification/tv/list`              | 无                         | 以国家代码为键的 `{ certifications }`，目录中每个国家一个键                    |
| `GET /watch/providers/regions`            | `language`                | `{ iso_3166_1, english_name, native_name }` 的 `{ results }` |
| `GET /watch/providers/movie`              | `language`、`watch_region` | 平台的 `{ results }`                                           |
| `GET /watch/providers/tv`                 | `language`、`watch_region` | 平台的 `{ results }`                                           |

`/configuration/countries` 和 `/configuration/languages` 会忽略 `language`，始终返回相同的名称。地区列表中的 `native_name` 遵循 `language`。amodb 不提供 `/configuration/timezones`。

一个分级条目写明分级名称、含义及其排序。条目按国家代码分组，所以一次调用覆盖所有市场。电影列表包含分级说明文字。在电视剧列表中，`meaning` 是空字符串。

```json
{
  "certifications": {
    "US": [
      { "certification": "PG", "meaning": "Some material may not be suitable for children under 10.", "order": 3 },
      { "certification": "R", "meaning": "Under 17 requires accompanying parent or adult guardian.", "order": 5 }
    ]
  }
}
```

示例缩减为 6 个美国条目中的 2 个。电影列表覆盖 AU、BR、CA、DE、ES、FR、GB、IT、RU 和 US。

一个平台条目包含 `provider_id`、`provider_name`、`logo_path`、`display_priority` 和 `display_priorities`，后者是国家代码到优先级的映射。不带 `watch_region` 时会得到所有平台。带 `watch_region=US` 时只保留服务该国家的平台。未知地区返回空的 `results` 数组。请传入来自 `/watch/providers/regions` 的代码。平台标志从图片主机加载，见[图片](https://amodb.dev/zh/images-api/)。

```json
{
  "display_priorities": { "AT": 1, "DE": 1, "GB": 1, "JP": 1, "US": 3 },
  "display_priority": 3,
  "logo_path": "/gMZdpavHmxFNnLpMHwVxfqeux2g.png",
  "provider_name": "Amazon Prime Video",
  "provider_id": 9
}
```

这是 `/watch/providers/movie?watch_region=US` 中的一个条目。

## 错误

| HTTP | status_code | 何时出现                            |
| ---- | ----------- | ------------------------------- |
| 401  | 7           | 密钥缺失或错误。                        |
| 402  | 36          | 套餐周期已结束。                        |
| 404  | 34          | 路径不存在，例如 `/genre/book/list`。    |
| 405  | 37          | 你对查找路径使用了写入方法。                  |
| 429  | 25          | 你超过了每分钟请求数。请等待 `Retry-After` 秒。 |

每个错误码的详情见[错误](https://amodb.dev/zh/errors/)。套餐限制见[速率限制](https://amodb.dev/zh/rate-limits/)。

## 实用说明

- 启动时按语言各加载一次列表，保存在内存或文件中。边缘节点把 `/configuration` 路径缓存 24 小时，所以你这边每天刷新一次就够了。
- 在数据库中保存类型 ID，而不是名称。名称会随语言变化，ID 不会。
- 两个类型路径返回同样的 27 项，所以一份映射覆盖电影和电视剧。ID 10759 以及 10762 到 10768 只出现在电视剧条目上。
- [发现](https://amodb.dev/zh/discover/)中的 `with_genres=28,12` 表示同时是动作和冒险。`with_genres=28|12` 表示二者之一。
- 类型名称遵循 `language` 参数。[语言](https://amodb.dev/zh/languages/)中 14 种基础语言之外的标签回退到英语，在某些语言中个别名称仍是英文，例如意大利语中的 `10759`。

## 常见问题

### 类型 ID 会随语言而变吗？

不会。ID 不变，只有名称被翻译。用你要显示的语言请求列表，然后在应用中为每种语言保留一份 ID 到名称的映射。

### 电影和电视剧使用不同的类型 ID 吗？

它们共用一个 ID 空间。两个类型路径返回同样的 27 个类型。电影条目使用 28 和 12 这样的 ID，电视剧条目使用合并后的 ID，例如动作冒险的 10759。一份映射就能覆盖两者。

### 如何同时按两个类型筛选？

把 with_genres 传给 discover。ID 之间的逗号表示全部满足，所以 28,12 表示同时是动作和冒险。竖线表示满足任意一个。用 without_genres 排除。

### 查找列表需要分页吗？

不需要。每个查找路径在一个响应中返回完整列表。启动时加载并缓存一天。配置路径在边缘缓存 24 小时。

## 相关页面

- [发现 API](https://amodb.dev/zh/discover/): 与 TMDB v3 筛选条件相同的 discover 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/languages/): amodb 以 14 种语言提供片名、简介和姓名。在 language 中传入 ru-RU 或 pt-BR 这样的 TMDB 风格标签，其他标签回退到英语。
- [图片 API 与图片主机](https://amodb.dev/zh/images-api/): 采用 TMDB v3 路径的电影图片 API：列出作品的海报、背景图、标志和剧照，再从 img.amodb.dev 以 10 种尺寸无密钥加载。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/genres/