替代方案能提供什么，不能提供什么

Kinopoisk 是俄语电影网站，没有公开的通用 API。开发者常转而使用第三方服务，各有各的条款，请查阅其文档。amodb 是独立的 API，并非 Kinopoisk 的服务。它覆盖俄语项目常见的三类需求：俄语的片名和简介、按 Kinopoisk ID 查找，以及在已知时把 Kinopoisk 评分与其他评分放在一起。

基本组成

你需要方法返回内容
俄语片名和简介在任意详情调用上加 language=ru-RU俄语的 title，original_title 不变
根据 Kinopoisk ID 找作品GET /3/find/361?external_source=kinopoisk_id带有 ID 550 的 movie_results
作品的 Kinopoisk IDGET /3/movie/550/external_ids字符串形式的 kinopoisk_id，此处为 "361"
Kinopoisk 评分GET /3/movie/550/ratings带 value 和 votes 的 kinopoisk，或为 null
乌克兰语或白俄罗斯语文本language=uk-UA 或 language=be-BY本地化字段，没有时为英语

下面的代码块展示了带有 append_to_response=ratings 的俄语详情响应。这是《搏击俱乐部》（ID 550）的真实响应，只保留了这里用到的字段，并缩短了简介。

JSON 
{
  "id": 550,
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из му...",
  "release_date": "1999-10-15",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб",
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2669989
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 67,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 81,
      "votes": null
    },
    "tmdb": {
      "value": 8.437,
      "votes": 33039
    }
  }
}

ratings 对象始终列出相同的五个键。这里 Kinopoisk 评分为 8.7，而它的 votes 是 null，所以不能默认一定有 Kinopoisk 投票数。详情见评分页。

功能对比

功能Kinopoiskamodb
定价模式没有通用的开放 API，第三方服务请查阅其文档预付，每次购买 1 至 24 个月
免费额度请查阅其文档无，也没有试用
认证方式请查阅其文档api_key 或 Bearer 请求头
响应格式请查阅其文档TMDB v3 格式的 JSON
语言俄语网站14 种界面语言，包括俄语
电影在网站上详情、演职员、图片、视频
电视剧在网站上剧集、季和集
人物在网站上资料和作品列表
图片在网站上img.amodb.dev，无需密钥
评分网站上自有的观众评分Kinopoisk 评分，另有四个来源（已知时）
速率限制请查阅其文档每个密钥每分钟 20、40 或 120 次
商业使用请查阅其文档付费套餐，见定价
兼容性没有通用的开放 API，请查阅其文档TMDB v3 读取接口和 OMDb

amodb 的不同之处

  • 有文档的契约。 路径、参数、错误响应体和限制都有明确记录，一个密钥可用于所有接口。
  • 俄语与其他语言并存。 同样的调用换一个 language 值，就能得到另一种语言的相同字段。当你的用户读俄语、乌克兰语和英语时，这很有帮助。
  • 一个对象中有多个评分。 你可以把 Kinopoisk 评分与 IMDb、Metacritic 和 Rotten Tomatoes 并排展示，未知的评分均为 null。
  • 保留原始片名。 original_title 和 original_name 以源语言保存片名，包括日语和韩语，尽管它们不是界面语言。

Kinopoisk 更适合的场景

  • 社区本身。 评论、列表、用户主页和本地讨论都在网站上。amodb 不提供这些，只在已知时给出评分。
  • 元数据之外的一切。 对于不属于元数据字段的内容，请使用网站本身。元数据 API 不承载这些内容。
  • 自有的观众评分。 这个数值最先在那里产生。在 amodb 中，新作品或冷门作品的评分可能为 null，即使评分已设置，投票数也可能为 null。

迁移到 amodb

收集你保存的 Kinopoisk ID，用 /3/find 一次性完成映射，并把数字形式的 amodb ID 保存在旁边。之后用俄语请求详情，并从同一个响应中读取评分。

Python 
import os
import requests

KEY = os.environ["AMODB_KEY"]
BASE = "https://api.amodb.dev/3"
HEADERS = {"Authorization": f"Bearer {KEY}"}


def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


found = get("/find/361", external_source="kinopoisk_id")
movie_id = found["movie_results"][0]["id"]
movie = get(f"/movie/{movie_id}", language="ru-RU", append_to_response="ratings")
kp = movie["ratings"]["kinopoisk"]
print(movie["title"], "/", movie["original_title"])
print("Kinopoisk:", kp["value"] if kp else "not known")

movie_results 数组为空表示该 ID 没有匹配项。剧集的 Kinopoisk ID 会填充 tv_results，因此在不确定类型时请同时读取两个数组。遇到 429 时，等待 Retry-After 指定的秒数。语言列表见语言页，查找规则见按外部 ID 查找页。

处理俄语文本的缺口

如果某部作品没有俄语译文，文本字段可能为空。请检查空字符串，并对该作品用 language=en-US 再请求一次。要获取带俄语字样的海报，请调用 /3/movie/550/images?include_image_language=ru,null，并从 posters 中挑选。null 值会把无文字的图稿保留在列表中。尺寸见图片页。

定价

amodb 没有免费额度。你在三个套餐之一上预付 1、3、6、12 或 24 个月，周期越长越便宜 10、20、30 或 40%。这些套餐允许每分钟 20、40 或 120 个请求，返回相同的数据，也不会自动续费。具体金额见定价。