MoviePilot/docs/site-api-integration.md

MoviePilot 站点 API 接入需求

适用对象：PT 站点开发者及接口维护者

适用范围：通过站点官方 API 接入 MoviePilot（以下简称 MP）

版本：1.0

日期：2026 年 11 月 4 日

本文说明站点需要提供哪些接口，才能支持 MP 的资源搜索、自动订阅、种子下载和用户数据展示。建议先打通“用户授权 → 搜索资源 → 获取种子文件”这一最小闭环，再补齐最新资源列表和用户数据。

本文中的 URL、字段名、权限名称和 JSON 结构均为建议示例，不是 MP 已发布的统一站点 API 标准。 站点可以沿用自己的接口，只要提供等价能力和完整文档，MP 侧再编写适配。已有接口满足需求时，无须专门复制一套接口。

1 接入能力与优先级

能力	优先级	用途	可以如何提供
适合后台长期使用的用户授权	基础必需	MP 代表用户访问本人有权限的数据	个人 API Key、长期 Token，或可自动续期的授权机制
资源搜索和分页	搜索必需	手动搜索、订阅补搜	关键词搜索接口
获取种子文件	下载必需	将选中资源交给下载器	直接返回 .torrent，或先生成下载链接
最新资源列表和分页	完整自动订阅所需	周期获取新发布资源	独立列表接口，或搜索接口支持空关键词与发布时间排序；也可提供可用 RSS
当前用户信息和统计	用户数据展示所需	展示账号等级、上传下载量、做种等	一个汇总接口，或拆分为多个接口
种子详情	按需必需	补齐搜索结果缺少的字段	搜索已返回全部所需字段时可省略
分类字典	推荐	将站点分类映射到电影、电视剧等	字典接口，或稳定的分类文档
未读消息、签到、收藏等	可选	扩展功能	按站点实际支持情况提供

最小接入不要求提供签到、消息、收藏、发种、账户管理等功能。用户统计不影响基础搜索和下载；缺少这些接口时，相关展示能力无法完整提供。

2 认证与授权

2.1 推荐采用个人 API Key 或 Token

建议用户在站点个人中心完成一次人工登录后，自行生成专门用于 MP 的访问凭据，并填入自己的 MP 实例。API 可以采用以下任一种鉴权方式：

Authorization: Bearer <USER_API_TOKEN>

或：

X-API-Key: <USER_API_KEY>

凭据应绑定具体用户，继承该用户的访问权限和下载限制。建议支持命名、查看使用时间、单独撤销和重新生成。用户主动撤销、账号被禁用或权限被取消后，接口应及时拒绝访问。

这里的“长期使用”不要求 Token 永不过期；关键是 MP 能在无人值守时持续工作。如果采用短期 Access Token，需要提供明确的刷新机制，并说明 Refresh Token 的有效期、轮换规则、并发刷新行为和失效后的重新授权方式。

2.2 建议权限范围

示例权限	允许的操作	需要该权限的能力
torrent:read	搜索、列表、读取种子详情	搜索和订阅
torrent:download	获取种子文件或生成下载链接	下载
user:read	读取本人账号信息和统计	用户数据展示
message:read	读取本人未读消息	可选
checkin:write	执行本人签到	可选

权限名称可以不同，也可以沿用站点既有权限模型。基础接入只需要资源读取和种子下载权限，不需要管理员权限。

2.3 请明确自动化访问条件

请说明以下事项：

• API 凭据从哪里生成，哪些用户等级可以生成，是否需要额外开通权限。
• 凭据是否过期，如何刷新或撤销，错误码分别是什么。
• 是否绑定 IP、User-Agent 或设备；如果绑定，如何支持 NAS、Docker、代理和公网 IP 变化。
• API 是否存在验证码、浏览器 JavaScript 挑战或必须交互的二次验证。建议用户授权时完成交互验证，正常 API 调用采用可独立校验的机器凭据。
• 下载接口是否沿用同一 API 凭据，还是需要单独的下载凭据。

能在网页中正常登录，或前端存在某个 Token 页面，并不能单独证明第三方客户端可以长期使用。需要确认实际账号可获得凭据，以及凭据可以访问哪些接口。

如采用 HMAC 或其他签名鉴权，请提供完整签名文档和不含真实密钥的测试向量，包括签名字符串组成、路径及查询参数规范化、请求体摘要、时间戳单位、允许时钟偏差、Nonce 规则、编码方式、签名算法及密钥获取方式。MP 应能依照公开协议计算签名，不应依赖复制网页内部临时状态。

3 资源搜索接口

3.1 建议请求

GET /api/v1/torrents?keyword=Example&page=1&page_size=50&sort=published_at&order=desc
Authorization: Bearer <USER_API_TOKEN>
Accept: application/json

也可以采用 POST 并传 JSON。HTTP 方法和路径可以不同，请保持参数含义明确。

参数	要求	说明
keyword	必需能力	支持中文和英文标题；说明多关键词按 AND、OR 还是整句匹配，以及搜索标题、副标题的范围
page / cursor	必需能力	页码或游标均可；明确页码从 0 还是 1 开始
page_size / limit	必需能力	明确默认值、最大值及实际返回数量
category	推荐	支持分类筛选；说明是否允许多个分类
sort、order	推荐	至少说明默认排序；最新列表需要可靠的发布时间降序
imdb_id、tmdb_id 等	可选	按媒体 ID 精确搜索；说明电影与剧集 ID 的区分
free_only 等促销筛选	可选	返回当前用户实际可用的促销资源

至少提供一种可靠的分页结束标识，例如 has_more、next_cursor 或 total。如果接口存在最多可翻页数、最多返回条数或历史搜索窗口，也请明确说明。

3.2 种子记录字段

以下“必需”是指完成稳定搜索与下载所需的信息，字段可以由搜索或必要的详情请求提供。为降低请求量，建议搜索和列表直接返回常用字段。

建议字段	要求	类型与含义
id	必需	站点内稳定、唯一的种子 ID，建议字符串；用于去重、详情及下载
title	必需	原始发布标题，保留年份、季集、分辨率、来源、编码、发布组等信息
size	必需	内容总大小，以字节为单位的整数，不是 .torrent 文件大小
download_url 或按 ID 下载规则	必需	二者至少提供一种；短时链接的生成方式见第 5 节
subtitle / description	推荐	副标题、中文名或补充说明；尽量提供纯文本
details_url	推荐	用户在浏览器中打开的种子详情页地址；也可以提供可拼接规则
published_at	推荐；最新列表需要	原始发布时间，明确时区；不要用置顶时间替代
seeders	强烈推荐	当前做种人数，非负整数，用于判断资源可用性
leechers	推荐	当前下载人数，非负整数
completed / grabs	推荐	累计完成次数，说明统计口径
category	推荐	稳定分类 ID 或名称，并提供分类映射
download_factor	有促销时需要	下载计费倍率，例如免费为 0，半价为 0.5，正常为 1
upload_factor	有促销时需要	上传计费倍率，例如正常为 1，双倍上传为 2
promotion_end_at	限时促销时推荐	当前有效促销的截止时间，长期有效或未知时按文档约定处理
hit_and_run	有 H&R 规则时推荐	是否受下载后保种规则约束；最好同时说明规则
labels	推荐	如中字、国语、官种、DIY、HDR、杜比视界等标签
imdb_id、tmdb_id、douban_id	可选但有帮助	辅助媒体识别；保留来源及完整 ID，不同来源不能混用
info_hash	可选	用于种子身份校验或去重；说明 v1/v2 类型

请注意以下语义：

• 标题需要保留发布信息。例如 Example.Movie.2026.2160p.WEB-DL... 比仅返回中文片名更有利于 MP 识别和筛选。
• 免费是“下载流量不计费”，与双倍上传分别表达。只返回 FREE、2X 等字符串也可以，但必须提供完整枚举映射。
• 促销数据最好由服务端合并全站活动、种子活动和用户权益后，返回对当前用户实际生效的倍率；否则请提供明确的优先级和计算规则。
• 如果促销规则未知，应允许表达未知，不能把缺失值当成免费。长期有效与截止时间未知也应可区分。
• 是否有权限下载、是否触发 H&R、是否免费是不同概念，不要复用同一个字段。
• 媒体 ID 要注明来源。对于 TMDB，还需说明是电影还是电视剧；单个种子包含多部作品时，不应随意指定其中一部代表全部内容。

3.3 建议响应示例

{
  "code": "OK",
  "data": {
    "items": [
      {
        "id": "123456",
        "title": "Example.Movie.2026.2160p.WEB-DL.H265-GROUP",
        "subtitle": "示例电影 / 国语 / 中英字幕",
        "details_url": "https://tracker.example/torrents/123456",
        "size": 21474836480,
        "published_at": "2026-11-04T08:00:00+08:00",
        "seeders": 50,
        "leechers": 3,
        "completed": 120,
        "category": "movie",
        "download_factor": 0,
        "upload_factor": 2,
        "promotion_end_at": "2026-11-05T08:00:00+08:00",
        "hit_and_run": false,
        "labels": ["国语", "中字"]
      }
    ],
    "page": 1,
    "page_size": 50,
    "has_more": false
  }
}

该示例采用“按种子 ID 调用下载接口”的方式，因此没有在搜索结果中返回下载链接。code 的类型和成功值可沿用站点规范；请提供全部业务错误码。

4 最新资源列表与自动订阅

为了支持 MP 周期性发现新发布资源，需要提供一种可靠的最新资源获取方式。

优先复用搜索接口：允许不传关键词，并按发布时间降序返回资源。

GET /api/v1/torrents?page=1&page_size=50&sort=published_at&order=desc

也可以提供独立接口：

GET /api/v1/torrents/latest?page=1&page_size=50

要求如下：

• 返回字段尽量与搜索结果一致，避免为每个新资源额外请求详情。
• 说明置顶、推荐、重复发布、编辑和删除资源的处理方式。
• 排序应稳定。相同发布时间可用种子 ID 作为第二排序键；更推荐使用稳定游标。
• 说明列表能回溯多长时间、最大条数，以及高发布量时如何翻页，避免轮询期间漏过新资源。
• 如支持 since、after_id 或增量游标，请说明边界是否包含、游标有效期，以及它表示发布时间还是更新时间。

RSS 可以作为替代入口，但需要实际可用的用户授权方式、稳定资源标识和可下载的 enclosure，并说明条数与更新时间。JSON 列表接口和 RSS 的具体使用方式，需要 MP 侧适配，不是新增接口后就自动启用。

如果暂时只能提供关键词搜索，仍可先支持手动搜索及部分订阅补搜；但不能据此认为最新资源轮询能力已经完整。

5 种子下载接口

以下两种方式任选一种即可。搜索返回一个种子 ID，并提供可按 ID 获取文件的接口，就能满足下载闭环，不要求搜索结果必须带永久下载 URL。

5.1 方式一 直接返回种子文件

GET /api/v1/torrents/123456/download
Authorization: Bearer <USER_API_TOKEN>

成功响应示例：

HTTP/1.1 200 OK
Content-Type: application/x-bittorrent
Content-Disposition: attachment; filename="123456.torrent"

<torrent binary data>

要求返回真实、完整、可解析的 .torrent 文件。私有站点的种子应包含适用于当前用户的 Tracker 认证信息，能被其下载器正常使用。

5.2 方式二 先获取短时下载地址

POST /api/v1/torrents/123456/download-link
Authorization: Bearer <USER_API_TOKEN>
Accept: application/json

{
  "code": "OK",
  "data": {
    "url": "https://download.example/torrent/123456?ticket=EXAMPLE_ONLY",
    "expires_at": "2026-11-04T08:05:00+08:00"
  }
}

随后由 MP 访问该 URL，取得实际种子文件。链接可以是签名 URL，不要求永久有效；建议在用户真正执行下载时才生成。

请明确：

• 换取链接使用 GET 还是 POST，参数放在何处，JSON 中哪个字段是实际地址。
• 链接有效期、是否单次有效，以及超时或网络失败后是否允许重试。
• 下载地址是否仍需 Header、Cookie、Referer 或特殊 User-Agent；建议签名 URL 本身即可完成授权。
• 是否有 IP 绑定，以及生成链接和下载文件是否必须来自同一出口 IP。
• 是否重定向到其他域名，目标域名和鉴权规则是什么。
• 重复获取文件是否消耗配额、重复登记下载，或产生其他业务副作用。
• 用户无下载权限、等级不足、账号受限、种子被删除、票据过期等场景分别返回什么错误。

不要在下载失败时返回 HTTP 200 的登录页、验证码页或错误 HTML。 如果采用 JSON 错误响应，应以内容类型和状态码清晰区分种子文件与错误信息。

仅提供网页详情地址不能完成下载闭环。仅提供不含用户 Tracker 认证信息的磁力链接，对私有站点通常也不足以替代可用的个性化种子文件。

6 当前用户信息与统计

如希望在 MP 中展示完整站点账号数据，建议提供一个当前用户汇总接口：

GET /api/v1/me
Authorization: Bearer <USER_API_TOKEN>

建议字段	用途及口径
id、username	用户唯一标识、显示名称
level	用户等级名称，或提供等级 ID 到名称的映射
joined_at	注册时间，注明时区
uploaded	累计计费上传量，单位字节
downloaded	累计计费下载量，单位字节
ratio	分享率；下载量为 0 时需约定 null 等表达方式，不使用非法 JSON 数值 Infinity
bonus	魔力、积分等数值；多种积分需区分名称和单位
seeding_count	当前做种数量
seeding_size	当前做种内容总体积，单位字节
leeching_count	当前下载数量
unread_message_count	未读消息数量，可选
updated_at	数据生成或最近更新时间，便于判断统计延迟

上传量、下载量请注明是原始流量还是计费流量，建议两者都有时分别返回。做种体积请说明同一种子在多个客户端做种时如何计数。

如果站点不能直接汇总做种体积，可以提供当前用户的做种列表，包含种子大小并支持分页，由 MP 适配后汇总；这会增加请求量，因此优先推荐直接返回汇总值。

这些信息可以拆成 /me、/me/stats 等多个接口。不需要允许 MP 查询任意用户的私人数据，也不要求开放用户管理接口。

7 分类字典与种子详情

7.1 分类字典

建议提供：

GET /api/v1/categories

每个分类至少包含稳定 ID、名称及大类归属，例如电影、电视剧、动漫、纪录片、音乐、综艺等。如果分类稳定且很少变动，提供完整的静态映射文档也可以，不强制增加接口。

7.2 种子详情

GET /api/v1/torrents/123456

详情接口用于补齐搜索或列表缺少的信息，例如副标题、促销、H&R、媒体 ID 或下载信息。搜索结果已经完整时，无须强制为每个资源调用详情。

如果搜索结果属于“资源合集”，而不是具体种子，请提供从合集展开到具体种子列表的方式。每个可下载种子需要独立 ID、标题、大小和下载能力。

8 可选扩展接口

以下能力可以后续增加，不应阻塞基础接入：

• 站内消息：未读数量、列表和详情；消息提供稳定 ID，方便去重。标记已读属于独立写操作，不能因读取消息而隐式触发，除非文档明确且双方认可。
• 签到：提供签到接口，明确已签到的返回值、每日时区及重复请求行为。
• 收藏或订阅书签：查询、添加和删除收藏；需要用户授予独立写权限。
• 用户做种和下载列表：用于更丰富的数据展示，提供分页和统计口径。
• 字幕：字幕列表、语言、格式和下载接口。
• 站点公告或活动信息：便于展示公告、全站促销和维护状态。
• 能力查询：返回 API 版本、支持功能及限制，方便客户端识别差异。

提供可选 API 并不意味着 MP 会自动获得对应功能；需要另行确认现有模块或插件的适配范围。

9 通用协议与运行约定

9.1 数据格式

• API 使用 HTTPS，JSON 文本使用 UTF-8。
• 大小和流量统一使用字节，人数和次数使用非负整数；积分及倍率允许小数。
• 时间推荐采用带时区的 ISO 8601；使用 Unix 时间戳时明确秒或毫秒。
• ID 建议采用字符串，避免超大整数在不同语言中丢失精度。
• 明确缺失字段、null、0 和空字符串的含义；未知数据不要伪装成确定的零值。
• 保持响应结构和枚举稳定；新增字段应尽量向后兼容，破坏性变更应提前通知并保留过渡期。

9.2 错误响应

建议同时使用正确的 HTTP 状态码和可供程序判断的业务错误码。例如：

{
  "code": "TOKEN_EXPIRED",
  "message": "API token has expired",
  "request_id": "example-request-id"
}

HTTP 状态	建议含义
400	参数无效
401	未认证、凭据无效或过期
403	已认证但无相应权限，或账号受限
404	资源不存在或已删除
429	请求过于频繁，建议返回 Retry-After
5xx	服务端异常或维护

如果站点已有不同状态码或统一业务码规范，可以沿用，但需要提供准确对照。搜索没有结果应成功返回空数组，不能与认证失败、限流或接口故障混为一谈。

9.3 请求频率和网络环境

请提供每个用户、Token、IP 的限流维度，统计窗口、允许请求数、并发数和下载频率限制。搜索、最新列表、用户统计和下载接口如果限制不同，请分别列出，并给出建议轮询周期。

MP 为用户自行部署的应用，请求通常由 NAS、Docker 或服务器发起。建议对正式机器 API 采用 Token 鉴权和明确限流策略，避免正常调用被交互式浏览器挑战拦截。IP 限制、地域限制和代理限制应提前说明。

基础接入为 MP 后端调用站点接口，通常不需要站点为 MP 前端单独开放 CORS，也不需要站点回调或主动连接用户的 MP 实例。

9.4 凭据与用户数据

API Token、下载票据和带 passkey 的 URL 都是敏感信息。文档和联调日志使用占位符或脱敏值；真实凭据不应写入公开 Issue、示例代码或公共仓库。接口按当前用户权限返回资源和个性化种子即可，无须共享管理员凭据或用户密码。

10 请站点提供的联调资料

1. 接口文档：Base URL、HTTP 方法、参数、请求 Header、字段类型、单位、成功及错误示例；OpenAPI 文档更方便，但不是硬性要求。
2. 授权说明：凭据生成入口、可用账号等级、权限范围、有效期、刷新及撤销方法，以及普通用户能否实际生成凭据。
3. 搜索说明：关键词匹配规则、分类字典、排序、分页、最大返回条数及历史数据范围。
4. 最新资源说明：空关键词是否可用、列表排序、增量或 RSS 能力、建议轮询间隔。
5. 下载说明：直接文件还是临时 URL、所需鉴权、有效期、IP 绑定、重定向和重试约定。
6. 业务枚举：分类、促销倍率、用户等级、H&R、账号状态和下载权限的解释。
7. 脱敏样例：至少覆盖普通种子、免费种子、双倍上传、限时促销、H&R、无权限和空搜索结果。
8. 测试安排：由双方约定私密授权渠道或测试环境，不在公开文档中附带真实 Token、Cookie、密码或 passkey。
9. 运行限制：限流、并发、维护响应、版本变更通知方式和技术联系人。

11 分阶段联调与验收

第一阶段 搜索和下载

• 用户能够生成、配置并撤销 API 凭据。
• MP 能完成中文、英文关键词搜索，并正确翻页和识别无结果。
• 标题、大小、人数和分类映射正确；有促销时，免费和倍率判断正确。
• MP 能按种子 ID 获取文件，或现场换取短时下载链接并取得文件。
• 下载器能够接受该种子并正常连接 Tracker，用户身份和权限正确。
• 凭据失效、权限不足、资源删除和限流时，MP 能收到可区分的错误。

第二阶段 自动订阅和用户数据

• 最新资源能按约定排序、分页或增量获取；覆盖高发布量和相同发布时间场景。
• 轮询和分页过程中能识别重复资源，并验证是否存在遗漏。
• 普通、免费、双倍上传、促销到期和 H&R 样例与站点页面一致。
• 用户等级、上传下载量、魔力、做种数和做种体积与站点统计口径一致。
• Token 生命周期、正常重试和限流退避能在无人值守条件下工作。

第三阶段 可选功能

按双方约定验收消息、签到、收藏、字幕等能力。

接口可以访问或返回 HTTP 200，仅代表连通性；实际接入完成还需要验证数据解析、用户权限、个性化种子下载和下载器使用结果。

12 MP 侧适配与责任分工

站点负责提供稳定、正式支持第三方客户端的 API、鉴权方式和协议文档。MP 侧负责将站点接口转换为内部搜索结果、下载请求和用户数据，并完成站点配置、索引及必要的专用适配。

MP 已有 API Key 搜索及临时下载地址的实现案例，但不会自动识别任意新站点的 JSON 格式。一般需要检查主后端的站点适配，以及站点资源生成和发布链路。适配工作量取决于接口结构、认证方式及字段完整程度。

建议对方先确认以下五项：能否签发适合无人值守使用的用户凭据，能否分页搜索，能否按 ID 下载种子，能否获取最新资源，能否读取本人统计。 前三项形成最小闭环，后两项完善自动订阅和站点数据展示。

附录 MP 当前实现参考

以下链接用于理解 MP 已有数据模型和适配方式，站点无须照搬内部字段或下载请求编码。

• 搜索结果模型 TorrentInfo：标题、大小、发布时间、人数、计费倍率、媒体身份等。
• 站点配置与用户数据模型：API Key、Token、站点请求限流及用户统计字段。
• Rousi API 适配示例：个人 API Key 搜索、分页，以及在下载时请求接口取得短时链接。
• MTorrent 适配示例：搜索结果转换与下载凭据生成。

实现参考核对日期为 2026 年 11 月 4 日。本文的接口路径、字段设计和验收建议是供双方协商的接入需求，不代表每个现有站点都已实现全部能力。