影视观看平台与流媒体片库查询 APIs

已知一部电影或剧集时，可直接传入影视 ID、tt 开头的 IMDb ID（如 tt0120338），或带 movie/、tv/ 前缀的 TMDB ID（如 movie/597、tv/1396），无需先按片名搜索。country 为可选的小写两字母国家代码；填写时限定观看地区，省略时请求所有支持国家的可用信息。响应数据是单个影视对象，不是列表，可包含 id、imdbId、tmdbId、title、originalTitle、overview、releaseYear、genres、directors、cast、rating、runtime、imageSet 和按国家归类的 streamingOptions。观看选项中可读取 service、type、link、音轨和字幕信息；画质、价格、附加频道和可用日期仅在有数据时出现。应按 type 区分会员包含、免费、租赁、购买和附加频道，不要将所有链接都标为会员可看。已知影片在某地区没有观看选项，不代表全球都不可看。series_granularity 的 show 只取作品级信息，season 包含季，episode 包含季与集；本接口默认 episode，只需要作品层面的观看入口时可改为 show。链接指向流媒体服务的作品页面，实际观看仍受平台权限与地区限制。

填写必填的 title 片名和 country 小写国家代码，查找候选电影与剧集。show_type 可限制为 movie 或 series，留空则同时搜索两类作品。响应数据直接是影视对象数组，没有 shows 外层字段，也不使用游标分页。候选项可包含影视 ID、IMDb 与 TMDB 标识、片名、原名、年份、简介、分类、导演、演员、评分、片长、图片和按国家归类的 streamingOptions。匹配依据是片名与作品类型，不是当地能否观看，因此候选作品可能在请求地区没有观看选项。请先通过年份、演员和标识确认作品，再检查对应国家的观看入口。通常最多返回 20 项，但完全同名的匹配超过 20 项时可返回全部完全匹配项，不能据此当作完整片库导出。series_granularity 默认 show；season 包含季，episode 包含季与集，仅影响剧集。需要保持条件连续翻页浏览片库时，应改用按筛选条件搜索接口。

在一个必填的 country 国家范围内浏览可观看的电影和剧集。catalogs 最多接受 32 个逗号分隔的片库选择器：netflix 这类平台 ID、prime.subscription 这类平台加访问方式，或 service.addon.addon_id 这类平台加附加频道标识；服务和频道 ID 应取自该国家目录。只填平台 ID 会包含其支持的观看方式，不等于仅会员包含；多个选择器按任意一个匹配，省略 catalogs 则搜索该国所有可用片库。可用分类目录返回的 genres ID 组合筛选，通过 genres_relation 选择同时满足或任一满足，并叠加片名或简介关键词、原始语言、年份和评分范围。order_by 支持原始片名、发行日期、评分及列出的热度周期；高分优先可选择 rating 和 order_direction=desc。响应数据为含 shows、hasMore 和可能的 nextCursor 的对象。每个作品可带标识、年份、简介、分类、演员、评分、片长、图片及该国观看选项，后者可能还包含所选片库之外的平台。仅当 hasMore=true 时才用 nextCursor 续页，其他筛选条件全部保持不变。无匹配时可返回 shows=[]、hasMore=false 且不含 nextCursor。电影或作品级页面每页 20 项，剧集的页大小随详情层级而变化。这里只提供发现资料和服务链接，不返回可播放媒体。

按必填 country、change_type 和 item_type 轮询片库变动。change_type 可选 new（新增）、removed（移除）、updated（更新）、expiring（即将到期）或 upcoming（即将上架）；item_type 可选 show、season、episode。show_type 用于将作品级变动进一步限定为电影或剧集。可选 catalogs 沿用片库搜索的 service、service.access_type 和 service.addon.addon_id 语法，最多 32 个逗号分隔选择器。响应数据含 changes 数组、以影视 ID 为键的 shows 映射、hasMore 及可能的 nextCursor；每条变动可含 changeType、itemType、showId、showType、streamingOptionType、service、link、timestamp，应通过 showId 关联 shows 中的作品资料。每页最多 25 条，按时间戳排序，order_direction 控制升降序。from 和 to 使用含边界的 Unix 秒级时间戳：new、removed、updated 限于过去 31 天，expiring、upcoming 限于未来 31 天，省略边界时覆盖对应规定窗口。未来条目的日期可能未知，include_unknown_dates 决定是否包含这些条目，不影响过去变动。仅在 hasMore=true 时传回 nextCursor，其他参数保持不变。这是轮询式变动查询，不是推送通知或无限期历史档案，也不保证每个平台都有未来日期数据。

获取支持国家的完整目录，output_language 可选 en、es、tr 或 fr。响应数据是以小写国家代码为键的对象，不是数组，也没有额外 countries 包装。每个国家条目包含 countryCode、name 和 services 数组；服务记录可含 id、name、homePage、themeColorCode、imageSet、streamingOptionTypes 与 addons，附加频道也有各自的标识、名称、主页和图片资料。美国目录可包含 Netflix、Prime Video、Disney+、Hulu 等服务，实际支持范围以当次返回为准。应使用返回的国家与平台 ID 构造片库查询，不固定宣传国家数量，也不假设同一平台在所有市场都有服务。streamingOptionTypes 仅表示平台支持的访问方式，并不证明某部作品在当地可看。此接口不返回影片级片库或某部作品的观看链接。

将支持的小写国家代码填入必填路径参数 country-code，例如 us，获取该地区的平台目录。output_language 支持 en、es、tr、fr，默认英语。响应数据是单个含 countryCode、name 和 services 的对象；服务条目可包含 id、name、homePage、themeColorCode、imageSet、带布尔标志的 streamingOptionTypes，以及 addons 数组。附加频道条目可带 id、name、homePage、themeColorCode 和 imageSet。使用该国家返回的平台与频道 ID，可构造 service.subscription 或 service.addon.addon_id 这样的片库选择器。addons 为空数组时，只表示此次响应没有为该服务列出频道。平台支持某种访问方式是目录能力，不证明某部电影或电视剧当前可看；具体观看入口必须通过作品自己的 streamingOptions 确认。

获取受支持的影视分类目录，output_language 可选 en、es、tr、fr。响应数据直接是包含 id 和 name 的对象数组，不分页，也没有额外 genres 字段。分类可包括 action、comedy、drama、scifi 等；请以返回目录为准，不固定假设分类总数。将 id 以逗号分隔填入片库搜索的 genres 参数，name 用于显示，不要将翻译后的分类名称作为筛选值。此接口仅返回分类参考，不含匹配作品、热度排名或各类片库数量。中文界面可以自行维护显示标签，但中文不是 output_language 已列出的输出选项。