# 搜索 API > 搜索接口把文本查询转成 ID。GET /3/search/movie 查找电影，同级路径查找电视剧、人物、系列合集、公司和关键词，multi 一次搜索全部。JSON 与 TMDB v3 一致，每页 20 条，边缘缓存查询 10 分钟。 ## 接口 `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` 响应: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [ 28, 878, 80 ], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40461 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [ 16, 28, 53 ], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [ 10402 ], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` ## 搜索电影 `GET /3/search/movie` 接收文本查询，返回分页的匹配电影列表，最佳匹配排在最前。用它把用户输入的内容转成电影 ID，再用这个 ID 调用[电影详情](https://amodb.dev/zh/movies/)。 示例搜索《盗梦空间》，限定为 2010 年，并打印 ID、标题和上映日期。 ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' }); const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_results } = await res.json(); console.log(`${total_results} matches`); for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/search/movie", params={"query": "inception", "year": 2010, "language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print(data["total_results"], "matches") for m in data["results"][:5]: print(m["id"], m["title"], m["release_date"]) ``` ```php 'inception', 'year' => 2010, '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"); } $data = json_decode($body, true); foreach (array_slice($data['results'], 0, 5) as $m) { echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type SearchPage struct { TotalResults int `json:"total_results"` Results []struct { ID int `json:"id"` Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), 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 p SearchPage if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.TotalResults, "matches") for _, m := range p.Results { fmt.Println(m.ID, m.Title, m.ReleaseDate) } } ``` ### 参数 | 参数 | 位置 | 必填 | 说明 | | ---------------------- | -- | --- | --------------------------------------------------------------- | | `query` | 查询 | 是 | 要搜索的文本。请做 URL 编码：空格变为 `%20` 或 `+`。 | | `api_key` | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。 | | `year` | 查询 | 否 | 四位数年份。保留在任何国家有该年上映日期的电影。 | | `primary_release_year` | 查询 | 否 | 四位数年份。只匹配首次上映日期，所以返回的作品可能比 `year` 少。 | | `region` | 查询 | 否 | 大写的两位国家代码，例如 `US`。已知该国日期时，用该国日期替换 `release_date`。它不会移除作品。 | | `include_adult` | 查询 | 否 | 接受但被忽略。成人作品永远不会返回。 | | `language` | 查询 | 否 | `en-US` 或 `it-IT` 这样的 TMDB 标签。提供 14 种基础语言，其他语言回退到英文。默认 `en-US`。 | | `page` | 查询 | 否 | 页码，1 到 500。默认 1。 | ### 响应字段 | 字段 | 类型 | 说明 | | ---------------------------------------- | ----------------- | ------------------------------------------------- | | `page` | integer | 你请求的页码。 | | `results` | array | 最多 20 条，最佳匹配在前。 | | `total_pages`、`total_results` | integer | 此查询结果集的大小。上限为 500 页和 10000 条结果。 | | `id` | integer | 用于详情接口的电影 ID。 | | `title`、`original_title` | string | 本地化标题和原始标题。 | | `original_language` | string | 电影制作语言的两位代码。 | | `overview` | string | 本地化文本，没有译文时为空。 | | `release_date` | string | `YYYY-MM-DD`，没有日期的作品为空。 | | `genre_ids` | array of integers | 类型 ID，不是名称。用[类型](https://amodb.dev/zh/genres/)映射。 | | `poster_path`、`backdrop_path` | string 或 null | 拼接到 `https://img.amodb.dev/t/p/{size}`。 | | `popularity`、`vote_average`、`vote_count` | number | 排名和评分值。 | | `adult`、`video` | boolean | `adult` 始终为 `false`。被标记为视频内容的条目，`video` 为 `true`。 | ### 示例响应 ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [28, 878, 80], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [16, 28, 53], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [10402], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` 响应包含全部三条匹配结果。它取自线上 API，只缩短了较长的 `overview` 字符串。 ## 其他搜索接口 下面每个路径都使用同一个基础地址 `https://api.amodb.dev/3`，都需要 `query`，并返回相同的 `page`、`results`、`total_pages` 和 `total_results` 外层结构。每个接口也都接受 1 到 500 的 `page`。所有接口都接受 `include_adult` 并忽略它。 | 方法和路径 | 查找内容 | 额外参数 | 条目字段 | | ------------------------ | ----------- | --------------------------------------- | --------------------------------------------------------------------------------- | | `GET /search/tv` | 电视剧 | `first_air_date_year`、`year`、`language` | `name`、`original_name`、`first_air_date`、`origin_country` | | `GET /search/person` | 人物 | `language` | `name`、`original_name`、`known_for_department`、`gender`、`profile_path`、`known_for` | | `GET /search/multi` | 电影、电视剧和人物合并 | `language` | `media_type` 加上该类型的字段 | | `GET /search/collection` | 电影系列合集 | `language` | `name`、`original_name`、`overview`、`poster_path`、`backdrop_path` | | `GET /search/company` | 制作公司 | 无 | `name`、`logo_path`、`origin_country` | | `GET /search/keyword` | 关键词 | 无 | `id`、`name` | 对于电视剧，`first_air_date_year` 只保留首播日期在该年的剧集，而 `year` 还会保留更早开播、但在该年播出过的剧集。用 `year=2010` 搜索 `the` 会返回 1989 年首播的《辛普森一家》，用 `first_air_date_year=2010` 做同样的搜索则不会。两个参数都传时，必须同时匹配。人物条目最多带 3 个 `known_for` 作品，每个都有 `media_type`。`/search/multi` 会忽略 `year`。 在这里找到的实体可以继续查看[电视剧](https://amodb.dev/zh/tv-series/)、[人物](https://amodb.dev/zh/people/)、[系列合集](https://amodb.dev/zh/collections/)、[公司和电视网](https://amodb.dev/zh/companies-networks/)以及[关键词](https://amodb.dev/zh/keywords/)。 ### multi 搜索 `media_type` 是 `movie`、`tv` 或 `person`，它告诉你该期望哪些字段。电影条目带有 `title`，电视剧和人物条目带有 `name`。 ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## 错误 `/search/tv` 和 `/search/person` 对没有匹配的查询返回 HTTP 200、空的 `results` 数组和为 0 的 `total_results`。目前 `/search/movie`、`/search/multi`、`/search/keyword`、`/search/company` 和 `/search/collection` 对同样的情况返回 HTTP 500 和 `status_code` 11。除非你确定匹配的查询也反复出现 500，否则请把这些路径上的 500 当作没有结果处理。 | HTTP | status_code | 何时出现 | | ---- | ----------- | ----------------------------------------------- | | 401 | 7 | 密钥缺失或错误。 | | 402 | 36 | 套餐周期已结束。 | | 405 | 37 | 你调用了写入方法。 | | 429 | 25 | 超过每分钟请求数。请等待 `Retry-After` 秒。 | | 500 | 11 | 电影、multi、关键词、公司或系列合集查询没有匹配，或 `page` 超出 1 到 500。 | | 504 | 24 | 后端未在时限内响应。请重试一次。 | 完整列表见[错误](https://amodb.dev/zh/errors/)，各窗口见[速率限制](https://amodb.dev/zh/rate-limits/)。 ## 实用说明 - 边缘缓存会把搜索结果保留 10 分钟，并在各密钥之间共享该副本。每次调用仍然计入你每分钟 20、40 或 120 个请求，因为速率限制在缓存之前执行。 - 做搜索框时，在最后一次按键后等待 300 毫秒，并取消正在进行的请求。每次按键都发请求的搜索框，可能在几秒内用完每分钟 20 个请求的套餐。 - 在你这一侧把查询用作缓存键之前，先转成小写并去掉首尾空白。 - 要按 IMDb ID 查找作品，请跳过搜索，使用[按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/)。 - `/search/keyword` 返回的关键词 ID 可用于[发现 API](https://amodb.dev/zh/discover/) 的 `with_keywords` 筛选，公司 ID 可用于 `with_companies`。 ## 常见问题 ### 一页搜索结果有多少条？ 每页 20 条结果，page 参数范围为 1 到 500。请读取响应中的 total_pages 和 total_results，并用 year 或 primary_release_year 缩小模糊查询的范围。 ### 命中缓存的搜索仍会计入速率限制吗？ 会。边缘缓存会把搜索结果保留 10 分钟，并在各密钥之间共享，但密钥检查和速率限制在缓存查找之前执行，所以每次调用都计一次。 ### 可以用这些接口按 IMDb ID 搜索吗？ 不可以。请改用 GET /3/find/{external_id} 并设置 external_source=imdb_id。它会返回该 ID 对应的 movie_results、tv_results 和 person_results，说明见按外部 ID 查找页。 ### 结果使用什么语言？ language 参数决定标题和简介的语言，默认 en-US。14 种基础语言以外的标签会回退到英文。原始标题仍可在 original_title 和 original_name 中获得。 ## 相关页面 - [电影详情 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 获取剧集的季、电视网和下一集，以及内容分级和观看平台。 - [人物详情 API](https://amodb.dev/zh/people/): 路径和 JSON 与 TMDB v3 相同的人物详情 API。按 ID 获取演员或幕后人员，含传记、作品列表、外部 ID 和热门列表。 - [发现 API](https://amodb.dev/zh/discover/): 与 TMDB v3 筛选条件相同的 discover API。按类型、演员、公司、关键词、年份、评分、时长和平台列出电影和剧集，并可排序。 - [按外部 ID 查找](https://amodb.dev/zh/find-by-external-id/): 用 TMDB find 接口按 IMDb、TVDB、Wikidata 或 Kinopoisk ID 查找电影、剧集或人物，并读取外部 ID。 - [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。 更新于: 2026-10-18. Source: https://amodb.dev/zh/search/