# 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 可以采用以下任一种鉴权方式：

```http
Authorization: Bearer <USER_API_TOKEN>
```

或：

```http
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 建议请求

```http
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 建议响应示例

```json
{
  "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 周期性发现新发布资源，需要提供一种可靠的最新资源获取方式。

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

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

也可以提供独立接口：

```http
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 方式一 直接返回种子文件

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

成功响应示例：

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

<torrent binary data>
```

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

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

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

```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 中展示完整站点账号数据，建议提供一个当前用户汇总接口：

```http
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 分类字典

建议提供：

```http
GET /api/v1/categories
```

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

### 7.2 种子详情

```http
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 状态码和可供程序判断的业务错误码。例如：

```json
{
  "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](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/domain/context.py)：标题、大小、发布时间、人数、计费倍率、媒体身份等。
- [站点配置与用户数据模型](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/schemas/site.py)：API Key、Token、站点请求限流及用户统计字段。
- [Rousi API 适配示例](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/modules/indexer/spider/rousi.py)：个人 API Key 搜索、分页，以及在下载时请求接口取得短时链接。
- [MTorrent 适配示例](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/modules/indexer/spider/mtorrent.py)：搜索结果转换与下载凭据生成。

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