{
  "openapi": "3.0.3",
  "info": {
    "title": "Drivemby 文档",
    "version": "2026-10-07",
    "description": "Drivemby 的 API 文档。**媒体库部分兼容 Emby 协议**，现有 Emby 客户端可以直接连接；**第三方 App 接入**（自动开号、上报目录）是 Drivemby 自己的接口。媒体库部分不是完整 Emby 服务端实现，仅承诺本文列出的能力；目前不提供转码。\n\n## 两种接入方式\n\n### 一、播放器：连接用户自己的 Drivemby 账号\n1. 用户在 Drivemby 网站用邮箱注册登录，在控制台「播放器连接」创建连接密码。\n2. 用邮箱和连接密码调用 `AuthenticateByName`，保存 `AccessToken` 与 `User.Id`。\n3. 之后的请求在 `X-Emby-Token`（或 `Authorization: Bearer`）里带上 `AccessToken`。\n4. 获取 `Views`，用分类 Id 作为 `ParentId` 浏览媒体，播放前请求 `PlaybackInfo`。\n\n### 二、第三方 App：替用户开号、上报 NAS 目录、播放\n适合自己能读到用户 WebDAV / SMB 目录的 App。用户全程不用去 Drivemby 网站操作：App 只上报文件名，Drivemby 识别整理成媒体库，App 再按 Emby 协议浏览和播放。\n\n0. **登记应用**：联系我们（官网「商务合作」）登记，得到 `appId` 与 `appSecret`。`appSecret` 只能放在你的服务器上，不能放进 App。\n1. **开号（你的服务器）**：用户在你的产品里已验证过邮箱后，你的服务器签名调用 `POST /partner/v1/accounts`。邮箱没有 Drivemby 账号就新建，有就直接关联。返回一次性 `grant`，交给 App。签名方法见「合作方开号」。\n2. **兑换（App）**：App 调用 `POST /partner/v1/grant/redeem`，带上 `grant` 和这个来源固定不变的 `agentId`，得到：\n   - `token`：Agent 令牌，用于下面的目录上报；\n   - `connectionPassword`：Emby 连接密码。每个应用每个账号只签发一个，之后再兑换返回 `null`，请保存好；丢了就传 `rotateConnection: true` 重签。\n3. **登录媒体库（App）**：用 `email` 与 `connectionPassword` 调用 `AuthenticateByName`，同方式一的第 2、3 步。\n4. **上报目录（App，带 Agent 令牌）**：\n   1. `POST /agent/v1/heartbeat`：上报挂载源与访问线路（SMB 填 `smb://主机`，WebDAV 填 `https://主机:端口`，都不带账号密码）。\n   2. 响应 `needSnapshot` 为 true，或指令里有 `full_snapshot` 时做全量：`snapshot/begin` → 多次 `snapshot/batch` → `snapshot/commit`。\n   3. 之后只报变化：`POST /agent/v1/changes`。收到 `rescan` 指令时重新遍历该目录，再按增量上报。\n   4. 移动端不需要常驻：在添加来源、回到前台、用户下拉刷新时各做一次心跳加增量即可。\n5. **等待整理**：提交全量后，Drivemby 在后台识别、刮削，作品陆续出现在 `Views` / `Items` 里，通常几分钟内。\n6. **播放**：`PlaybackInfo` 返回的 SMB 来源是 `Protocol: File` 和不带账号的 `smb://主机/共享/路径`，App 按地址找到自己保存的共享账号直接打开；WebDAV 来源是不带认证的 http 地址，App 自己补上认证头。播放进度照常用 `Sessions/Playing` 上报。\n\n### 第三方接入的错误处理\n| 接口 | 状态码与错误码 | 处理 |\n| --- | --- | --- |\n| accounts | 401 `invalid_signature` / `stale_signature` / `replayed` | 检查签名、服务器时钟、nonce 是否重复 |\n| accounts | 403 `app_revoked` | 用户在 Drivemby 撤销了你的应用，提示用户到 Drivemby 控制台「播放器连接 → 已关联的应用」重新允许 |\n| accounts | 409 `email_in_use` / `account_linked_to_other` | 你的用户换成的新邮箱已经是另一个 Drivemby 账号，或这个 Drivemby 账号已关联你的另一个用户；联系我们处理 |\n| redeem | 401 `invalid_grant` | 票据过期、已用或授权已撤销：重新走第 1 步 |\n| redeem | 409 `drive_limit` / `agent_in_use`、400 参数错误 | 票据不会用掉，修正后可重试 |\n| /agent/v1/* | 401 | 令牌已撤销：重新走第 1、2 步 |\n| /agent/v1/* | 403 `vip_required` / `trial_one_drive` / `trial_device_used` / `trial_changes_used` | 账号不是会员且不能（再）试用，或试用已用在另一个网盘 / 来源上：目录暂不处理；开通会员后原令牌直接可用，不用重新开号 |\n| 媒体库接口 | 401 | 连接密码已失效（用户撤销了应用或改了密码）：重新走第 1、2 步，兑换时传 `rotateConnection: true` 拿新密码，再重新登录 |\n| /agent/v1/* | 409 `stale_epoch` | 本轮全量已失效，重新 `snapshot/begin` |\n| 全部 | 429 | 按 `Retry-After`（秒）退避；全量同步每个来源每天最多 6 次 |\n\n用户随时可以在 Drivemby 控制台查看、撤销你的应用；撤销后 Agent 令牌和连接密码立即失效。\n\n**会员与试用**：没试用过的免费账号首次上报时在这个来源上开始免费试用（1 个来源、1 个媒体库目录、识别约 100 个单元、其中 50 部可播放）；更多需要会员。用户可以在 Drivemby 网站开通；也可以由你为自己的付费用户开通（合作授权，联系我们），之后按邮箱自动生效。\n\n**限流**：`AuthenticateByName` 每个 IP 加邮箱 10 分钟 20 次；`grant/redeem` 每个 IP 10 分钟 60 次；`accounts` 每个 IP 每分钟 300 次，另按应用登记的额度限流。\n\n## 兼容范围与扩展\n路径支持服务器根路径和 `/emby` 前缀，媒体库接口默认 `/emby`。取片源（PlaybackInfo、视频流、字幕）需要有效会员或试用额度；浏览、图片、观看状态与播放上报只需登录。**播放历史 PlaybackHistory、待看 Watchlist、UserData.IsWatchlisted、详情 Images、MediaSources[].Origin 和 ServerDomains 是 Drivemby 扩展**，不属于标准 Emby 接口契约。分类以标准 CollectionFolder 下发，电影与剧集分别为 movies / tvshows。\n\n## 在线调试\n在线调试会向当前服务器发出真实请求，写操作会修改账号数据。授权仅留在当前页面内存，刷新后需重新填写；不要分享连接密码、Token 或签名播放地址。\n\n## 通用约定\nJSON 错误为 `{error:{code,message}}`。400 参数无效；401 会话失效；403 权限不足；404 不存在或不可见；409 状态冲突；429 限流；502 无可用播放来源。分页从 0 开始，时间位置使用 ticks（每秒 10,000,000）。"
  },
  "servers": [
    {
      "url": "/emby",
      "description": "当前服务器 · Emby 前缀"
    },
    {
      "url": "/",
      "description": "当前服务器 · 根路径兼容"
    }
  ],
  "tags": [
    {
      "name": "合作方开号",
      "description": "第三方 App 接入的第 1、2 步。`/partner/v1/accounts` 只能由你的服务器调用，用 `appSecret` 签名；`/partner/v1/grant/redeem` 由 App 直接调用，凭一次性票据，不带签名。\n\n**签名**：每个请求带 4 个请求头：\n\n| 请求头 | 内容 |\n| --- | --- |\n| `X-Drivemby-App` | 你的 `appId` |\n| `X-Drivemby-Timestamp` | 当前 Unix 秒，与服务器相差不超过 5 分钟 |\n| `X-Drivemby-Nonce` | 16–64 位随机串（字母、数字、`_`、`-`），10 分钟内不能重复 |\n| `X-Drivemby-Signature` | 见下 |\n\n签名 = 小写十六进制的 `HMAC-SHA256(appSecret, appId + \"\\n\" + 时间戳 + \"\\n\" + nonce + \"\\n\" + sha256十六进制(原始请求体))`。请求体要按签名时的原样发送。\n\n```js\nimport { createHash, createHmac, randomBytes } from 'node:crypto';\nconst body = JSON.stringify({ email, emailVerifiedAt, externalUserId, scopes: ['agent:register', 'connections:write'] });\nconst ts = String(Math.floor(Date.now() / 1000)), nonce = randomBytes(16).toString('base64url');\nconst bodyHash = createHash('sha256').update(body).digest('hex');\nconst signature = createHmac('sha256', appSecret).update(`${appId}\\n${ts}\\n${nonce}\\n${bodyHash}`).digest('hex');\nawait fetch('https://drivemby.com/partner/v1/accounts', { method: 'POST', body, headers: {\n  'Content-Type': 'application/json', 'X-Drivemby-App': appId, 'X-Drivemby-Timestamp': ts,\n  'X-Drivemby-Nonce': nonce, 'X-Drivemby-Signature': signature } });\n```"
    },
    {
      "name": "目录上报",
      "description": "第三方 App 接入的第 4 步：把用户来源里的目录和文件名报给 Drivemby。请求头 `Authorization: Bearer <Agent 令牌>`，请求体可以 gzip（`Content-Encoding: gzip`）。\n\n**挂载源与线路**（心跳里的 `mounts` 与 `access`）：\n- 挂载源是来源下的一个顶层目录，比如 SMB 的每个共享、或 WebDAV 来源本身；名字就是它在 Drivemby 里的媒体库名。\n- 只上报文件名的客户端：`mounts[].mode` 填 `remote`，`access.mode` 填 `source`。\n- `access.lines[]` 是播放线路，`baseUrl` 不带账号密码：SMB 填 `smb://主机[:端口]`，`auth` 必须为 `none`；WebDAV 填 `https://主机[:端口]`。\n- `access.mountPaths` 把挂载源名映射到它在服务上的路径：SMB 填 `/共享名`；WebDAV 填基础路径，就在服务根目录时填 `/`（留空会被当成 `/挂载源名`）。\n\n**节点**（`snapshot/batch` 的 `items`、`changes` 的 `upserts`）：\n- `ref` = `挂载源名/相对路径`，用 `/` 分隔、不以 `/` 开头，最长 1000 字节；必须等于 `parentRef + \"/\" + name`。\n- 挂载源本身也是一个节点：`{ref: \"电影\", parentRef: \"\", name: \"电影\", isDir: true}`。\n- 只报目录、视频、`.nfo` 和外挂字幕（srt / ass / ssa / vtt）。图片（jpg、png 等）会被当作本地海报，并按 http 线路下发图片地址；只有 SMB 线路时不要上报图片，否则海报打不开（不上报就用 TMDB 图）。其他文件会被忽略。\n- 文件带 `size`（字节）和 `mtime`（Unix 秒）；目录不带 `size`。\n- 父目录必须先于子项上报；每批最多 5000 条，多了分批。\n\n**同步**：\n- 全量：`snapshot/begin` 拿到 `epoch` → 多次 `snapshot/batch` → `snapshot/commit`。提交后，本轮没出现的节点视为已删除。每个来源每天最多 6 次全量。\n- 增量：`changes` 的 `upserts` 是新增或大小 / 修改时间变了的节点，`deletes` 是消失的 `ref`；删除目录只需上报目录本身。\n- 某个目录列举失败时整次放弃，不要把没列出来的子树当成删除。\n- 请求体压缩后最多 8MB、解压后最多 32MB。限流按令牌计：心跳每分钟 30 次，`snapshot/batch` 与 `changes` 每分钟 120 次，`begin` / `commit` 每分钟 10 次。\n- 心跳响应里的 `commands`：`full_snapshot` 重新全量；`rescan {ref}` 重新遍历该子树后按增量上报；`update` 只对 Drivemby 自己的 NAS 程序有意义，可以忽略。"
    },
    {
      "name": "服务与认证",
      "description": "登录与会话。连接密码来自控制台「播放器连接」，或合作方 App 兑换得到。"
    },
    {
      "name": "分类与媒体",
      "description": "浏览分类、作品、季和集。"
    },
    {
      "name": "图片",
      "description": "海报、背景、Logo 等图片，302 到图片地址。"
    },
    {
      "name": "播放",
      "description": "取片源与播放上报。需要有效会员或试用额度。"
    },
    {
      "name": "观看与状态",
      "description": "继续观看、收藏、已看。"
    },
    {
      "name": "其他兼容接口",
      "description": "为兼容常见 Emby 客户端提供的接口。"
    },
    {
      "name": "Drivemby 扩展",
      "description": "标准 Emby 没有的能力：独立待看清单、播放历史、服务器地址列表。"
    }
  ],
  "x-tagGroups": [
    {
      "name": "第三方 App 接入",
      "tags": [
        "合作方开号",
        "目录上报"
      ]
    },
    {
      "name": "媒体库（Emby 兼容）",
      "tags": [
        "服务与认证",
        "分类与媒体",
        "图片",
        "播放",
        "观看与状态",
        "其他兼容接口"
      ]
    },
    {
      "name": "Drivemby 扩展",
      "tags": [
        "Drivemby 扩展"
      ]
    }
  ],
  "security": [
    {
      "EmbyToken": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/System/Info/Public": {
      "get": {
        "tags": [
          "服务与认证"
        ],
        "summary": "获取公开服务器信息",
        "description": "无需登录。",
        "operationId": "get__System_Info_Public",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServerInfo"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/Users/Public": {
      "get": {
        "tags": [
          "服务与认证"
        ],
        "summary": "公开用户列表（空）",
        "description": "不公开账号信息，始终返回空数组。",
        "operationId": "get__Users_Public",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/Users/AuthenticateByName": {
      "post": {
        "tags": [
          "服务与认证"
        ],
        "summary": "使用邮箱和服务连接密码登录",
        "description": "连接密码在控制台「播放器连接」创建，或由合作方 App 通过 /partner/v1/grant/redeem 取得。不是邮箱验证码或 Passkey。保存 AccessToken 和 User.Id；打开认证设置 输入 Token。",
        "operationId": "post__Users_AuthenticateByName",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "User": {
                      "$ref": "#/components/schemas/User"
                    },
                    "AccessToken": {
                      "type": "string",
                      "description": "后续请求携带的会话 Token"
                    },
                    "ServerId": {
                      "type": "string"
                    },
                    "SessionInfo": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "Username": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "Pw": {
                    "type": "string",
                    "format": "password",
                    "description": "自定义连接密码或默认生成的 6 位数字；旧版 dmb_ 长密码仍兼容"
                  },
                  "Password": {
                    "type": "string",
                    "format": "password",
                    "description": "兼容别名，与 Pw 至少提供一项"
                  }
                },
                "required": [
                  "Username"
                ]
              }
            }
          }
        }
      }
    },
    "/Sessions/Logout": {
      "post": {
        "tags": [
          "服务与认证"
        ],
        "summary": "注销当前会话",
        "description": "注销当前 Token。",
        "operationId": "post__Sessions_Logout",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}": {
      "get": {
        "tags": [
          "服务与认证"
        ],
        "summary": "获取当前用户资料",
        "description": "PrimaryImageTag 对应 Drivemby 默认 Logo。",
        "operationId": "get__Users_uid_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/System/Info": {
      "get": {
        "tags": [
          "服务与认证"
        ],
        "summary": "获取服务器信息",
        "description": "",
        "operationId": "get__System_Info",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServerInfo"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/System/Ping": {
      "get": {
        "tags": [
          "服务与认证"
        ],
        "summary": "检查会话连通性",
        "description": "",
        "operationId": "get__System_Ping",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "服务与认证"
        ],
        "summary": "检查会话连通性",
        "description": "",
        "operationId": "post__System_Ping",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/System/Ext/ServerDomains": {
      "get": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "获取服务器地址",
        "description": "",
        "operationId": "get__System_Ext_ServerDomains",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Views": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取分类媒体库",
        "description": "复用后台分类，拆成「动画 · 电影」「动画 · 剧集」等非空媒体库，另有未识别入口。电影 CollectionType=movies，剧集=tvshows。使用返回的 Id 作为 Items 的 ParentId。同一作品跨分类 ID 和用户状态一致。",
        "operationId": "get__Users_uid_Views",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Items": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "查询媒体列表",
        "description": "电影分类默认以合集聚合；以合集 Id 为 ParentId 获取成员。筛选收藏、已看、待看等状态时不合并合集。",
        "operationId": "get__Items",
        "parameters": [
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "ParentId",
            "in": "query",
            "description": "分类、合集或季的 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Recursive",
            "in": "query",
            "description": "递归查询",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "IncludeItemTypes",
            "in": "query",
            "description": "逗号分隔，如 Movie,Series",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SearchTerm",
            "in": "query",
            "description": "名称搜索",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Ids",
            "in": "query",
            "description": "逗号分隔的媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "AnyProviderIdEquals",
            "in": "query",
            "description": "多个 ID 为任一匹配，最多100个。格式 Tmdb.157744,Tmdb.243224 或 Imdb.tt1234567",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "IsPlayed",
            "in": "query",
            "description": "已看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsFavorite",
            "in": "query",
            "description": "收藏筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsWatchlisted",
            "in": "query",
            "description": "Drivemby 扩展：待看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Filters",
            "in": "query",
            "description": "支持 IsPlayed、IsUnplayed、IsFavorite、IsFavoriteOrLiked",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortBy",
            "in": "query",
            "description": "逗号分隔排序字段：SortName、DateCreated、DateAdded、PremiereDate、ProductionYear、DatePlayed、DateWatchlisted、PlayCount、ParentIndexNumber、IndexNumber",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortOrder",
            "in": "query",
            "description": "排序方向",
            "schema": {
              "type": "string",
              "enum": [
                "Ascending",
                "Descending"
              ],
              "default": "Ascending"
            }
          },
          {
            "name": "GroupItemsIntoCollections",
            "in": "query",
            "description": "电影分类默认合并合集；false 返回单部电影",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Genres",
            "in": "query",
            "description": "逗号分隔的类型名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Studios",
            "in": "query",
            "description": "逗号分隔的制作方名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartItemId",
            "in": "query",
            "description": "从指定条目开始，包含该条目",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Items": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "查询媒体列表",
        "description": "电影分类默认以合集聚合；以合集 Id 为 ParentId 获取成员。筛选收藏、已看、待看等状态时不合并合集。",
        "operationId": "get__Users_uid_Items",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "ParentId",
            "in": "query",
            "description": "分类、合集或季的 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Recursive",
            "in": "query",
            "description": "递归查询",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "IncludeItemTypes",
            "in": "query",
            "description": "逗号分隔，如 Movie,Series",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SearchTerm",
            "in": "query",
            "description": "名称搜索",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Ids",
            "in": "query",
            "description": "逗号分隔的媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "AnyProviderIdEquals",
            "in": "query",
            "description": "多个 ID 为任一匹配，最多100个。格式 Tmdb.157744,Tmdb.243224 或 Imdb.tt1234567",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "IsPlayed",
            "in": "query",
            "description": "已看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsFavorite",
            "in": "query",
            "description": "收藏筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsWatchlisted",
            "in": "query",
            "description": "Drivemby 扩展：待看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Filters",
            "in": "query",
            "description": "支持 IsPlayed、IsUnplayed、IsFavorite、IsFavoriteOrLiked",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortBy",
            "in": "query",
            "description": "逗号分隔排序字段：SortName、DateCreated、DateAdded、PremiereDate、ProductionYear、DatePlayed、DateWatchlisted、PlayCount、ParentIndexNumber、IndexNumber",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortOrder",
            "in": "query",
            "description": "排序方向",
            "schema": {
              "type": "string",
              "enum": [
                "Ascending",
                "Descending"
              ],
              "default": "Ascending"
            }
          },
          {
            "name": "GroupItemsIntoCollections",
            "in": "query",
            "description": "电影分类默认合并合集；false 返回单部电影",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Genres",
            "in": "query",
            "description": "逗号分隔的类型名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Studios",
            "in": "query",
            "description": "逗号分隔的制作方名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartItemId",
            "in": "query",
            "description": "从指定条目开始，包含该条目",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Items/{id}": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取媒体详情及完整图片候选",
        "description": "Images 是 Drivemby 扩展，直接返回图片类型、索引、tag、语言、尺寸和无字标记。列表优先带字海报与背景，详情优先无字，缺失时回退。详情加载后应更新图片 tag；单集 Primary 仍为剧照。",
        "operationId": "get__Users_uid_Items_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Items/Latest": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取最新内容",
        "description": "注意：此接口返回数组，不是 Items 包装对象。",
        "operationId": "get__Users_uid_Items_Latest",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Item"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Items/Resume": {
      "get": {
        "tags": [
          "观看与状态"
        ],
        "summary": "获取继续观看",
        "description": "UserData 包含 PlaybackPositionTicks、LastPlayedDate；已知总时长时返回 PlayedPercentage，未知则省略。",
        "operationId": "get__Users_uid_Items_Resume",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Shows/{id}/Seasons": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取剧集季列表",
        "description": "id 为 Series ID。",
        "operationId": "get__Shows_id_Seasons",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Shows/{id}/Episodes": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取单集列表",
        "description": "id 为 Series ID；包含季集编号、单集元数据、文件来源。季号0表示特别篇。",
        "operationId": "get__Shows_id_Episodes",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "ParentId",
            "in": "query",
            "description": "分类、合集或季的 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Recursive",
            "in": "query",
            "description": "递归查询",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "IncludeItemTypes",
            "in": "query",
            "description": "逗号分隔，如 Movie,Series",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SearchTerm",
            "in": "query",
            "description": "名称搜索",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Ids",
            "in": "query",
            "description": "逗号分隔的媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "AnyProviderIdEquals",
            "in": "query",
            "description": "多个 ID 为任一匹配，最多100个。格式 Tmdb.157744,Tmdb.243224 或 Imdb.tt1234567",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "IsPlayed",
            "in": "query",
            "description": "已看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsFavorite",
            "in": "query",
            "description": "收藏筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsWatchlisted",
            "in": "query",
            "description": "Drivemby 扩展：待看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Filters",
            "in": "query",
            "description": "支持 IsPlayed、IsUnplayed、IsFavorite、IsFavoriteOrLiked",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortBy",
            "in": "query",
            "description": "逗号分隔排序字段：SortName、DateCreated、DateAdded、PremiereDate、ProductionYear、DatePlayed、DateWatchlisted、PlayCount、ParentIndexNumber、IndexNumber",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortOrder",
            "in": "query",
            "description": "排序方向",
            "schema": {
              "type": "string",
              "enum": [
                "Ascending",
                "Descending"
              ],
              "default": "Ascending"
            }
          },
          {
            "name": "GroupItemsIntoCollections",
            "in": "query",
            "description": "电影分类默认合并合集；false 返回单部电影",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Genres",
            "in": "query",
            "description": "逗号分隔的类型名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Studios",
            "in": "query",
            "description": "逗号分隔的制作方名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartItemId",
            "in": "query",
            "description": "从指定条目开始，包含该条目",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SeasonId",
            "in": "query",
            "description": "季 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Season",
            "in": "query",
            "description": "季号",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "UserId",
            "in": "query",
            "description": "当前用户 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Shows/NextUp": {
      "get": {
        "tags": [
          "分类与媒体"
        ],
        "summary": "获取下一集",
        "description": "根据观看记录返回下一未看普通集；有续播时不重复返回。",
        "operationId": "get__Shows_NextUp",
        "parameters": [
          {
            "name": "SeriesId",
            "in": "query",
            "description": "可限定一部剧集",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Items/{id}/PlaybackInfo": {
      "get": {
        "tags": [
          "播放"
        ],
        "summary": "获取最终可播放地址",
        "description": "Path / DirectStreamUrl 是最终绝对地址，无需再调 stream。按 RequiredHttpHeaders 设置媒体请求头；部分网盘签名绑定 UA，请提供实际播放请求的 PlaybackUserAgent。地址过期后重新获取。当前不转码。NAS 的 SMB 来源：Protocol 为 File，Path 为不带账号的 smb:// 地址（逐段编码），不提供 DirectStreamUrl 与认证头，客户端用自己保存的共享账号访问；对这类来源 stream 入口返回 409 smb_source；它的外挂字幕流（MediaStreams 中 IsExternal 为 true）带 Path，是字幕在共享上的 smb:// 地址，请从共享直接读取，不要用 DeliveryUrl。GET 从 query 读取，POST 可使用 JSON；重复身份参数必须一致。",
        "operationId": "get__Items_id_PlaybackInfo",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "UserId",
            "in": "query",
            "description": "当前用户 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "可选，选择具体来源",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PlaybackUserAgent",
            "in": "query",
            "description": "实际播放请求的 User-Agent；未提供时使用本次请求 UA",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaybackInfo"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "播放"
        ],
        "summary": "获取最终可播放地址",
        "description": "Path / DirectStreamUrl 是最终绝对地址，无需再调 stream。按 RequiredHttpHeaders 设置媒体请求头；部分网盘签名绑定 UA，请提供实际播放请求的 PlaybackUserAgent。地址过期后重新获取。当前不转码。NAS 的 SMB 来源：Protocol 为 File，Path 为不带账号的 smb:// 地址（逐段编码），不提供 DirectStreamUrl 与认证头，客户端用自己保存的共享账号访问；对这类来源 stream 入口返回 409 smb_source；它的外挂字幕流（MediaStreams 中 IsExternal 为 true）带 Path，是字幕在共享上的 smb:// 地址，请从共享直接读取，不要用 DeliveryUrl。GET 从 query 读取，POST 可使用 JSON；重复身份参数必须一致。",
        "operationId": "post__Items_id_PlaybackInfo",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "UserId",
            "in": "query",
            "description": "当前用户 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "可选，选择具体来源",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PlaybackUserAgent",
            "in": "query",
            "description": "实际播放请求的 User-Agent；未提供时使用本次请求 UA",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaybackInfo"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybackRequest"
              }
            }
          }
        }
      }
    },
    "/Sessions/Playing": {
      "post": {
        "tags": [
          "播放"
        ],
        "summary": "开始播放",
        "description": "使用获取 PlaybackInfo 的同一登录会话，并携带 PlaySessionId 与所选 MediaSourceId。PositionTicks 每秒10,000,000。Playing 立即记录历史；Progress/Stopped 保存位置，不要求先满30秒。自动已看另需有效播放证据和可信文件时长，上报的 RunTimeTicks 不作为依据。",
        "operationId": "post__Sessions_Playing",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlayEvent"
              }
            }
          }
        }
      }
    },
    "/Sessions/Playing/Progress": {
      "post": {
        "tags": [
          "播放"
        ],
        "summary": "上报进度",
        "description": "使用获取 PlaybackInfo 的同一登录会话，并携带 PlaySessionId 与所选 MediaSourceId。PositionTicks 每秒10,000,000。Playing 立即记录历史；Progress/Stopped 保存位置，不要求先满30秒。自动已看另需有效播放证据和可信文件时长，上报的 RunTimeTicks 不作为依据。",
        "operationId": "post__Sessions_Playing_Progress",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlayEvent"
              }
            }
          }
        }
      }
    },
    "/Sessions/Playing/Stopped": {
      "post": {
        "tags": [
          "播放"
        ],
        "summary": "结束播放",
        "description": "使用获取 PlaybackInfo 的同一登录会话，并携带 PlaySessionId 与所选 MediaSourceId。PositionTicks 每秒10,000,000。Playing 立即记录历史；Progress/Stopped 保存位置，不要求先满30秒。自动已看另需有效播放证据和可信文件时长，上报的 RunTimeTicks 不作为依据。",
        "operationId": "post__Sessions_Playing_Stopped",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlayEvent"
              }
            }
          }
        }
      }
    },
    "/Sessions/Playing/Ping": {
      "post": {
        "tags": [
          "播放"
        ],
        "summary": "播放心跳（兼容空操作）",
        "description": "当前只返回成功，不保存进度；请用 Progress 更新观看记录。",
        "operationId": "post__Sessions_Playing_Ping",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/FavoriteItems/{id}": {
      "post": {
        "tags": [
          "观看与状态"
        ],
        "summary": "添加收藏",
        "description": "独立更新此状态，不修改其他状态或播放进度。不需要请求体，兼容 application/json 空请求体。",
        "operationId": "post__Users_uid_FavoriteItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "观看与状态"
        ],
        "summary": "取消收藏",
        "description": "独立更新此状态，不修改其他状态或播放进度。不需要请求体，兼容 application/json 空请求体。",
        "operationId": "delete__Users_uid_FavoriteItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/PlayedItems/{id}": {
      "post": {
        "tags": [
          "观看与状态"
        ],
        "summary": "添加已看",
        "description": "手动标记或取消已看会清空当前播放位置。不改变收藏或待看。不需要请求体。",
        "operationId": "post__Users_uid_PlayedItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "观看与状态"
        ],
        "summary": "取消已看",
        "description": "手动标记或取消已看会清空当前播放位置。不改变收藏或待看。不需要请求体。",
        "operationId": "delete__Users_uid_PlayedItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/WatchlistItems/{id}": {
      "post": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "添加待看",
        "description": "独立更新此状态，不修改其他状态或播放进度。不需要请求体，兼容 application/json 空请求体。",
        "operationId": "post__Users_uid_WatchlistItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "取消待看",
        "description": "独立更新此状态，不修改其他状态或播放进度。不需要请求体，兼容 application/json 空请求体。",
        "operationId": "delete__Users_uid_WatchlistItems_id_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Watchlist": {
      "get": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "获取独立待看清单",
        "description": "默认 DateWatchlisted / Descending；强制待看筛选、不合并合集。标记已看不会自动移出待看。列表与详情 UserData.IsWatchlisted 返回状态。后台「观看与清单」与此接口共用数据。",
        "operationId": "get__Users_uid_Watchlist",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "ParentId",
            "in": "query",
            "description": "分类、合集或季的 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Recursive",
            "in": "query",
            "description": "递归查询",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "IncludeItemTypes",
            "in": "query",
            "description": "逗号分隔，如 Movie,Series",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SearchTerm",
            "in": "query",
            "description": "名称搜索",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Ids",
            "in": "query",
            "description": "逗号分隔的媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "AnyProviderIdEquals",
            "in": "query",
            "description": "多个 ID 为任一匹配，最多100个。格式 Tmdb.157744,Tmdb.243224 或 Imdb.tt1234567",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "IsPlayed",
            "in": "query",
            "description": "已看筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "IsFavorite",
            "in": "query",
            "description": "收藏筛选",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Filters",
            "in": "query",
            "description": "支持 IsPlayed、IsUnplayed、IsFavorite、IsFavoriteOrLiked",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SortBy",
            "in": "query",
            "description": "逗号分隔排序字段：SortName、DateCreated、DateAdded、PremiereDate、ProductionYear、DatePlayed、DateWatchlisted、PlayCount、ParentIndexNumber、IndexNumber",
            "schema": {
              "type": "string",
              "default": "DateWatchlisted"
            }
          },
          {
            "name": "SortOrder",
            "in": "query",
            "description": "排序方向",
            "schema": {
              "type": "string",
              "enum": [
                "Ascending",
                "Descending"
              ],
              "default": "Descending"
            }
          },
          {
            "name": "Genres",
            "in": "query",
            "description": "逗号分隔的类型名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Studios",
            "in": "query",
            "description": "逗号分隔的制作方名称",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartItemId",
            "in": "query",
            "description": "从指定条目开始，包含该条目",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/Items/{id}/HideFromResume": {
      "post": {
        "tags": [
          "观看与状态"
        ],
        "summary": "隐藏或恢复继续观看",
        "description": "不清空播放位置。",
        "operationId": "post__Users_uid_Items_id_HideFromResume",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Hide",
            "in": "query",
            "description": "true 隐藏，false 恢复",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserData"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Items/{id}/Images/{type}": {
      "get": {
        "tags": [
          "图片"
        ],
        "summary": "获取媒体图片",
        "description": "支持 Primary、Backdrop、Logo，按 tag 或类型内索引读取候选；不存在的图片404。详情 Images 提供完整候选，没有独立图片列表接口。",
        "operationId": "get__Items_id_Images_type_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      },
      "head": {
        "tags": [
          "图片"
        ],
        "summary": "获取媒体图片",
        "description": "支持 Primary、Backdrop、Logo，按 tag 或类型内索引读取候选；不存在的图片404。详情 Images 提供完整候选，没有独立图片列表接口。",
        "operationId": "head__Items_id_Images_type_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      }
    },
    "/Items/{id}/Images/{type}/{index}": {
      "get": {
        "tags": [
          "图片"
        ],
        "summary": "获取媒体图片",
        "description": "支持 Primary、Backdrop、Logo，按 tag 或类型内索引读取候选；不存在的图片404。详情 Images 提供完整候选，没有独立图片列表接口。",
        "operationId": "get__Items_id_Images_type_index_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "图片类型内索引，从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      },
      "head": {
        "tags": [
          "图片"
        ],
        "summary": "获取媒体图片",
        "description": "支持 Primary、Backdrop、Logo，按 tag 或类型内索引读取候选；不存在的图片404。详情 Images 提供完整候选，没有独立图片列表接口。",
        "operationId": "head__Items_id_Images_type_index_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "图片类型内索引，从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      }
    },
    "/Users/{uid}/Images/{type}": {
      "get": {
        "tags": [
          "图片"
        ],
        "summary": "获取默认用户头像",
        "description": "仅支持 Primary 和索引0，返回项目默认 Logo。只需登录。",
        "operationId": "get__Users_uid_Images_type_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      },
      "head": {
        "tags": [
          "图片"
        ],
        "summary": "获取默认用户头像",
        "description": "仅支持 Primary 和索引0，返回项目默认 Logo。只需登录。",
        "operationId": "head__Users_uid_Images_type_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      }
    },
    "/Users/{uid}/Images/{type}/{index}": {
      "get": {
        "tags": [
          "图片"
        ],
        "summary": "获取默认用户头像",
        "description": "仅支持 Primary 和索引0，返回项目默认 Logo。只需登录。",
        "operationId": "get__Users_uid_Images_type_index_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "图片类型内索引，从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      },
      "head": {
        "tags": [
          "图片"
        ],
        "summary": "获取默认用户头像",
        "description": "仅支持 Primary 和索引0，返回项目默认 Logo。只需登录。",
        "operationId": "head__Users_uid_Images_type_index_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "图片类型内索引，从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "响应中的图片内容标签",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "图片字节",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "重定向到图片地址",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "图片不存在"
          }
        }
      }
    },
    "/Videos/{id}/stream": {
      "get": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "get__Videos_id_stream",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      },
      "head": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "head__Videos_id_stream",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      }
    },
    "/Videos/{id}/stream.{ext}": {
      "get": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "get__Videos_id_stream_ext_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ext",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      },
      "head": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "head__Videos_id_stream_ext_",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ext",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      }
    },
    "/Items/{id}/Download": {
      "get": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "get__Items_id_Download",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      },
      "head": {
        "tags": [
          "播放"
        ],
        "summary": "302 跳转到媒体地址",
        "description": "兼容入口，通常直接使用 PlaybackInfo 的最终地址。",
        "operationId": "head__Items_id_Download",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MediaSourceId",
            "in": "query",
            "description": "具体来源 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "媒体重定向",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "未登录"
          },
          "403": {
            "description": "权限不足"
          },
          "404": {
            "description": "来源不存在"
          },
          "502": {
            "description": "媒体地址获取失败"
          }
        }
      }
    },
    "/Items/Counts": {
      "get": {
        "tags": [
          "其他兼容接口"
        ],
        "summary": "统计媒体数量",
        "description": "",
        "operationId": "get__Items_Counts",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "MovieCount": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "SeriesCount": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "EpisodeCount": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "ItemCount": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Genres": {
      "get": {
        "tags": [
          "其他兼容接口"
        ],
        "summary": "获取类型",
        "description": "",
        "operationId": "get__Genres",
        "parameters": [
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "Items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "Id": {
                            "type": "string"
                          },
                          "Name": {
                            "type": "string"
                          },
                          "ImageTags": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "TotalRecordCount": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Studios": {
      "get": {
        "tags": [
          "其他兼容接口"
        ],
        "summary": "获取制作方",
        "description": "",
        "operationId": "get__Studios",
        "parameters": [
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "Items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "Id": {
                            "type": "string"
                          },
                          "Name": {
                            "type": "string"
                          },
                          "ImageTags": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "TotalRecordCount": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Items/{id}/Similar": {
      "get": {
        "tags": [
          "其他兼容接口"
        ],
        "summary": "获取相似媒体",
        "description": "",
        "operationId": "get__Items_id_Similar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Videos/{id}/AdditionalParts": {
      "get": {
        "tags": [
          "其他兼容接口"
        ],
        "summary": "获取附加片段（空）",
        "description": "当前返回空数组。",
        "operationId": "get__Videos_id_AdditionalParts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Item"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/PlaybackHistory": {
      "get": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "获取播放历史",
        "description": "每次实际播放会话一条记录，按 StartedAt、Id 倒序。优先使用 NextCursor 续页，不要同时使用 Cursor 和 StartIndex。与后台历史共用数据；不等同于继续观看或已看清单。",
        "operationId": "get__Users_uid_PlaybackHistory",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "StartIndex",
            "in": "query",
            "description": "从0开始",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "Limit",
            "in": "query",
            "description": "每页最多200条",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "Cursor",
            "in": "query",
            "description": "上页 NextCursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SearchTerm",
            "in": "query",
            "description": "按作品名搜索",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ItemId",
            "in": "query",
            "description": "限定媒体 ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoryList"
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/PlaybackHistory/{historyId}": {
      "delete": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "删除一条播放历史",
        "description": "仅删除历史，保留收藏、待看、已看及续播进度。已删除会话的迟到上报不会重新创建记录。",
        "operationId": "delete__Users_uid_PlaybackHistory_historyId_",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "historyId",
            "in": "path",
            "required": true,
            "description": "图片类型",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Users/{uid}/PlaybackHistory/Clear": {
      "post": {
        "tags": [
          "Drivemby 扩展"
        ],
        "summary": "清空截止时间前的播放历史",
        "description": "仅清空当前账号的历史；Before 是包含边界的截止时间。",
        "operationId": "post__Users_uid_PlaybackHistory_Clear",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "当前用户 ID，必须与 Token 对应",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "deleted": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "Before": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-09-23T00:00:00Z"
                  }
                },
                "required": [
                  "Before"
                ]
              }
            }
          }
        }
      }
    },
    "/partner/v1/accounts": {
      "post": {
        "tags": [
          "合作方开号"
        ],
        "summary": "为已验证的邮箱开通或关联账号",
        "description": "只能由合作方服务器调用，appSecret 绝不能放进 App。邮箱不存在时新建免费账号（之后用户用同一邮箱验证码登录即可接管）；已存在时直接关联，不改登录方式和会员。同一 externalUserId 换了邮箱时视为用户改了邮箱（你须已验证新邮箱归属）：Drivemby 账号邮箱跟着改，片库、会员、连接密码不变；新邮箱已是另一个 Drivemby 账号时返回 409 email_in_use。一个账号只能关联该应用的一个用户（冲突返回 409 account_linked_to_other）。用户在控制台撤销后返回 403 app_revoked，直到用户重新允许；管理员账号不能关联（403 account_not_linkable）。按应用每分钟、每天新建账号数，以及每个邮箱每天次数限流。",
        "operationId": "post__partner_v1_accounts",
        "parameters": [
          {
            "name": "X-Drivemby-App",
            "in": "header",
            "required": true,
            "description": "登记的 appId",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Drivemby-Timestamp",
            "in": "header",
            "required": true,
            "description": "Unix 秒，与服务器相差不超过 5 分钟",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Drivemby-Nonce",
            "in": "header",
            "required": true,
            "description": "16–64 位随机串（字母数字 _ -），10 分钟内不能重复",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Drivemby-Signature",
            "in": "header",
            "required": true,
            "description": "hex(HMAC-SHA256(appSecret, appId + \"\\n\" + 时间戳 + \"\\n\" + nonce + \"\\n\" + hex(sha256(原始请求体))))",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "description": "Drivemby 账号 ID"
                    },
                    "email": {
                      "type": "string",
                      "description": "规范化后的邮箱"
                    },
                    "created": {
                      "type": "boolean",
                      "description": "本次是否新建了账号"
                    },
                    "grant": {
                      "type": "string",
                      "description": "一次性授权票据（dmbg_ 开头），交给自己的 App 兑换"
                    },
                    "grantExpiresIn": {
                      "type": "integer",
                      "format": "int64",
                      "description": "票据有效秒数",
                      "example": 300
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "you@example.com"
                  },
                  "emailVerifiedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "合作方验证邮箱归属的时间"
                  },
                  "externalUserId": {
                    "type": "string",
                    "description": "合作方自己的用户 ID"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "agent:register",
                        "connections:write"
                      ]
                    }
                  },
                  "readyWebhook": {
                    "type": "string",
                    "nullable": true,
                    "description": "整理完成通知地址（公网 http/https）：你上报的某个来源首次整理完成时，Drivemby 向它 POST 一条 drivemby.library.ready 汇总事件 {Event, Title, Description, Date, Server, Source:{name, agentId}, Counts:{works, matched, unmatched}}；与用户自己的入库 Webhook 分开，只发这一条汇总。不传不改，传 null 清除"
                  },
                  "trial": {
                    "type": "boolean",
                    "default": true,
                    "description": "新建账号时是否可以免费试用（按你自己的风控判断，如同一台设备只给一次）；只对本次新建的账号生效，关联已有账号时忽略。为 false 时上报返回 403 trial_device_used"
                  }
                },
                "required": [
                  "email",
                  "emailVerifiedAt",
                  "externalUserId",
                  "scopes"
                ]
              }
            }
          }
        }
      }
    },
    "/partner/v1/grant/redeem": {
      "post": {
        "tags": [
          "合作方开号"
        ],
        "summary": "App 兑换授权票据",
        "description": "App 直接调用，不带鉴权头，凭据不经合作方服务器。票据 5 分钟内有效、只能用一次。agent:register 需要 agentId 与 name：同一 agentId 复用同一个 NAS 账号：同一用户的多台设备可以各自兑换，同一应用每个来源保留最近 5 张令牌，更早的作废。非会员也会拿到令牌：没试用过的免费账号首次上报即在这个来源上开始试用；不能试用的上报时 /agent/v1/* 返回 403 vip_required / trial_one_drive，开通会员后无需重新兑换。连接密码每个应用每个账号只保留一个，名称为「应用名 · 设备名」；rotateConnection 为 true 时作废旧的并重签。参数不全（400）、网盘名额已满（409 drive_limit）、agentId 已被其他接入使用（409 agent_in_use）时票据不会用掉，可以修正后重试。",
        "operationId": "post__partner_v1_grant_redeem",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "token": {
                      "type": "string",
                      "description": "Agent 令牌（dmba_ 开头），用于 /agent/v1/*；没有 agent:register 时为 null",
                      "nullable": true
                    },
                    "driveAccountId": {
                      "type": "string",
                      "description": "NAS 账号 ID"
                    },
                    "heartbeatSec": {
                      "type": "integer",
                      "format": "int64",
                      "description": "建议心跳间隔",
                      "example": 60
                    },
                    "connectionPassword": {
                      "type": "string",
                      "description": "Emby 连接密码（connections:write）；该应用已有有效连接密码或名额已满时为 null",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant": {
                    "type": "string"
                  },
                  "agentId": {
                    "type": "string",
                    "description": "8–64 位，字母数字 _ -；同一来源保持不变"
                  },
                  "name": {
                    "type": "string",
                    "description": "NAS 名称（控制台显示）"
                  },
                  "deviceName": {
                    "type": "string",
                    "description": "设备名，用于连接密码名称"
                  },
                  "version": {
                    "type": "string",
                    "description": "客户端版本"
                  },
                  "rotateConnection": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "required": [
                  "grant"
                ]
              }
            }
          }
        }
      }
    },
    "/agent/v1/heartbeat": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "心跳：上报挂载源、访问线路与状态",
        "description": "access.lines[].baseUrl 支持 http / https / smb。smb 线路形如 smb://主机[:端口]，auth 必须为 none、地址不能带账号；mountPaths 把挂载源名映射到共享（如 电影 → /电影）。WebDAV 线路填协议、主机、端口，挂载源路径填基础路径，就在服务根目录时填「/」（留空按 /挂载源名）。",
        "operationId": "post__agent_v1_heartbeat",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "commands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "full_snapshot",
                              "rescan",
                              "update"
                            ]
                          },
                          "ref": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "heartbeatSec": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "needSnapshot": {
                      "type": "boolean",
                      "description": "还没有完成过全量同步"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "string"
                  },
                  "mounts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 128,
                          "description": "挂载源名，即节点 ref 的第一段，也是媒体库名"
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "local",
                            "remote"
                          ],
                          "description": "只上报文件名的客户端填 remote"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "dir",
                            "webdav"
                          ],
                          "description": "选填，只用于控制台展示"
                        }
                      }
                    },
                    "maxItems": 64
                  },
                  "phase": {
                    "type": "string"
                  },
                  "access": {
                    "type": "object",
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "webdav",
                          "source"
                        ]
                      },
                      "lines": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^[a-z0-9]{1,16}$",
                              "description": "线路 ID，小写字母数字，1–16 位",
                              "example": "lan"
                            },
                            "name": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 20,
                              "description": "线路名，会出现在来源名前面"
                            },
                            "baseUrl": {
                              "type": "string",
                              "description": "不带账号密码；最长 300 字符",
                              "example": "smb://192.168.1.10"
                            },
                            "auth": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "basic"
                                  ],
                                  "description": "smb 线路必须为 none"
                                }
                              }
                            }
                          }
                        },
                        "maxItems": 8
                      },
                      "imageLineId": {
                        "type": "string",
                        "description": "图片线路，只能是 http 线路"
                      },
                      "mountPaths": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "status": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent/v1/snapshot/begin": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "开始全量同步",
        "description": "每个 NAS 每天最多 6 次。",
        "operationId": "post__agent_v1_snapshot_begin",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "epoch": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ]
      }
    },
    "/agent/v1/snapshot/batch": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "全量同步：上传一批节点",
        "description": "父目录先于子节点，每批最多 5000 条，可 gzip（Content-Encoding: gzip）。",
        "operationId": "post__agent_v1_snapshot_batch",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "epoch": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ref": {
                          "type": "string",
                          "maxLength": 1000,
                          "description": "挂载源名/相对路径，最长 1000 字节",
                          "example": "电影/A (2014)/a.mkv"
                        },
                        "parentRef": {
                          "type": "string",
                          "description": "父目录 ref，挂载源节点为空字符串",
                          "example": "电影/A (2014)"
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 512,
                          "example": "a.mkv"
                        },
                        "isDir": {
                          "type": "boolean"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "字节数"
                        },
                        "mtime": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Unix 秒"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent/v1/snapshot/commit": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "提交全量同步",
        "description": "提交后没有出现在本轮的节点视为已删除，各挂载源自动成为媒体库。",
        "operationId": "post__agent_v1_snapshot_commit",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "videos": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "folders": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "epoch": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent/v1/changes": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "增量变化",
        "description": "upserts 与 deletes（ref 路径）各最多 5000 条，可 gzip。",
        "operationId": "post__agent_v1_changes",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "upserts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ref": {
                          "type": "string",
                          "maxLength": 1000,
                          "description": "挂载源名/相对路径，最长 1000 字节",
                          "example": "电影/A (2014)/a.mkv"
                        },
                        "parentRef": {
                          "type": "string",
                          "description": "父目录 ref，挂载源节点为空字符串",
                          "example": "电影/A (2014)"
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 512,
                          "example": "a.mkv"
                        },
                        "isDir": {
                          "type": "boolean"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "字节数"
                        },
                        "mtime": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Unix 秒"
                        }
                      }
                    }
                  },
                  "deletes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent/v1/status": {
      "get": {
        "tags": [
          "目录上报"
        ],
        "summary": "上报与识别进度",
        "description": "用 Agent 令牌查询这个来源的进度，用于在 App 里显示「已上报 N 个视频 · 已识别 x/y」。不要求会员或试用。",
        "operationId": "get__agent_v1_status",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "uploading",
                        "waiting",
                        "recognizing",
                        "done"
                      ],
                      "description": "uploading 全量清单还没提交；waiting 还没有媒体目录；recognizing 整理中；done 全部识别完成"
                    },
                    "videos": {
                      "type": "integer",
                      "format": "int64",
                      "description": "已上报的视频数"
                    },
                    "folders": {
                      "type": "integer",
                      "format": "int64",
                      "description": "已上报的文件夹数"
                    },
                    "lastSnapshotAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "lastSeenAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "units": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "format": "int64"
                        },
                        "matched": {
                          "type": "integer",
                          "format": "int64"
                        },
                        "unmatched": {
                          "type": "integer",
                          "format": "int64"
                        },
                        "pending": {
                          "type": "integer",
                          "format": "int64"
                        }
                      }
                    },
                    "works": {
                      "type": "integer",
                      "format": "int64",
                      "description": "识别出的作品数"
                    },
                    "membership": {
                      "type": "string",
                      "enum": [
                        "vip",
                        "trial",
                        "free"
                      ]
                    },
                    "trial": {
                      "type": "object",
                      "nullable": true,
                      "description": "试用中：{works 可播放上限, playable 已用, capped 是否扫满停下}"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ]
      }
    },
    "/agent/v1/unregister": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "注销来源",
        "description": "用户在你的 App 里删除这个来源、并选择同时删除 Drivemby 上的内容时调用：删掉这个来源在 Drivemby 的 NAS 账号、整理结果和 Agent 令牌，效果同控制台「解绑」，令牌随即失效。不要求会员或试用。用户选择保留时不要调用，之后由用户在 Drivemby 控制台自己管理。试用登记在这个来源上时，删掉后可以把试用换到新来源（已用的播放名额不返还，最多更换 3 次）。",
        "operationId": "post__agent_v1_unregister",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        }
      }
    },
    "/agent/v1/content": {
      "post": {
        "tags": [
          "目录上报"
        ],
        "summary": "上传 NFO 内容（可选）",
        "description": "只用于本地能读到文件内容的来源；只上报文件名的客户端不需要调用。每次最多 200 条，body 不超过 256KB，hash 为 NFO 全文 SHA1（小写）。",
        "operationId": "post__agent_v1_content",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "accepted": {
                      "type": "integer",
                      "format": "int64",
                      "description": "收下的条数"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "会话无效或已过期",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "权限或 VIP 不满足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "不存在、不可见或不属于当前用户",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "触发限流，请稍后重试",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "外部服务暂不可用或没有可用播放来源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "/",
            "description": "当前服务器"
          }
        ],
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ref": {
                          "type": "string",
                          "description": "NFO 文件的 ref"
                        },
                        "hash": {
                          "type": "string",
                          "description": "全文 SHA1"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "nfo"
                          ]
                        },
                        "body": {
                          "type": "string",
                          "description": "NFO 文本"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "EmbyToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Emby-Token",
        "description": "AuthenticateByName 返回的 AccessToken；与 Bearer 二选一。"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Emby 会话 Token，不是服务连接密码。"
      },
      "AgentToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Agent 令牌（dmba_ 开头）：接入码登录或合作方票据兑换得到。"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码",
                "example": "invalid_params"
              },
              "message": {
                "type": "string",
                "description": "错误说明",
                "example": "分页参数无效"
              }
            }
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "description": "当前用户 ID"
          },
          "Name": {
            "type": "string",
            "description": "绑定邮箱",
            "example": "you@example.com"
          },
          "ServerId": {
            "type": "string"
          },
          "PrimaryImageTag": {
            "type": "string",
            "description": "默认 Logo 内容哈希"
          },
          "HasPassword": {
            "type": "boolean",
            "description": "已配置密码"
          },
          "HasConfiguredPassword": {
            "type": "boolean",
            "description": "已配置密码"
          },
          "Configuration": {
            "type": "object",
            "additionalProperties": true
          },
          "Policy": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "UserData": {
        "type": "object",
        "properties": {
          "Key": {
            "type": "string",
            "description": "作品 ID"
          },
          "IsFavorite": {
            "type": "boolean",
            "description": "收藏状态"
          },
          "IsWatchlisted": {
            "type": "boolean",
            "description": "Drivemby 扩展：独立待看状态"
          },
          "Played": {
            "type": "boolean",
            "description": "已看状态"
          },
          "PlaybackPositionTicks": {
            "type": "integer",
            "format": "int64",
            "description": "播放时间单位：10,000,000 ticks = 1 秒。",
            "example": 600000000,
            "minimum": 0
          },
          "PlayCount": {
            "type": "integer",
            "format": "int64",
            "description": "播放次数",
            "example": 1
          },
          "LastPlayedDate": {
            "type": "string",
            "description": "最后观看时间；尚未观看时不提供",
            "example": "2026-09-23T00:00:00Z",
            "format": "date-time"
          },
          "PlayedPercentage": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "已知总时长时返回百分比；未知时省略",
            "example": 5
          }
        }
      },
      "Image": {
        "type": "object",
        "properties": {
          "ImageType": {
            "type": "string",
            "enum": [
              "Primary",
              "Backdrop",
              "Logo"
            ]
          },
          "ImageIndex": {
            "type": "integer",
            "format": "int64",
            "description": "同一类型内索引",
            "example": 0
          },
          "ImageTag": {
            "type": "string",
            "description": "图片版本标签"
          },
          "Path": {
            "type": "string",
            "description": "图片路径"
          },
          "Url": {
            "type": "string",
            "description": "可访问图片地址；本地图片可为站内相对地址"
          },
          "Width": {
            "type": "integer",
            "format": "int64",
            "description": "TMDB 图片宽度",
            "example": 1000
          },
          "Height": {
            "type": "integer",
            "format": "int64",
            "description": "TMDB 图片高度",
            "example": 1500
          },
          "Language": {
            "type": "string",
            "description": "TMDB 语言标记",
            "nullable": true
          },
          "IsTextless": {
            "type": "boolean",
            "description": "依据 TMDB 语言标记识别无字图片"
          }
        }
      },
      "MediaSource": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "description": "播放来源 ID"
          },
          "Name": {
            "type": "string",
            "description": "文件名",
            "example": "Example.S01E01.mp4"
          },
          "Type": {
            "type": "string",
            "example": "Default"
          },
          "Protocol": {
            "type": "string",
            "example": "Http"
          },
          "IsRemote": {
            "type": "boolean",
            "description": "远程文件"
          },
          "Container": {
            "type": "string",
            "example": "mp4"
          },
          "Size": {
            "type": "integer",
            "format": "int64",
            "description": "文件字节数"
          },
          "Path": {
            "type": "string",
            "description": "仅 PlaybackInfo 提供最终可播放地址"
          },
          "DirectStreamUrl": {
            "type": "string",
            "description": "仅 PlaybackInfo 提供最终可播放地址"
          },
          "RequiredHttpHeaders": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "播放时必须附带的请求头，例如 User-Agent"
          },
          "SupportsDirectPlay": {
            "type": "boolean",
            "description": "支持直接播放"
          },
          "SupportsDirectStream": {
            "type": "boolean",
            "description": "支持直连"
          },
          "SupportsTranscoding": {
            "type": "boolean",
            "description": "当前始终 false，不提供转码"
          },
          "MediaStreams": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "Origin": {
            "$ref": "#/components/schemas/MediaSourceOrigin",
            "description": "Drivemby 扩展：这个来源在哪个网盘、哪个目录。同一作品有多个版本时，用它区分和展示各版本；条目详情、列表与 PlaybackInfo 都返回"
          }
        }
      },
      "PlaybackInfo": {
        "type": "object",
        "properties": {
          "PlaySessionId": {
            "type": "string",
            "description": "播放上报需要的会话 ID"
          },
          "MediaSources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MediaSource"
            }
          }
        }
      },
      "PlaybackRequest": {
        "type": "object",
        "properties": {
          "UserId": {
            "type": "string",
            "description": "当前用户 ID"
          },
          "MediaSourceId": {
            "type": "string",
            "description": "可选，选择具体来源"
          },
          "PlaybackUserAgent": {
            "type": "string",
            "description": "实际播放请求的 User-Agent；未提供时使用本次请求 UA"
          }
        }
      },
      "PlayEvent": {
        "type": "object",
        "properties": {
          "ItemId": {
            "type": "string",
            "description": "作品或单集 ID"
          },
          "PlaySessionId": {
            "type": "string",
            "description": "PlaybackInfo 返回的会话 ID",
            "minLength": 32,
            "maxLength": 32
          },
          "MediaSourceId": {
            "type": "string",
            "description": "所选来源 ID；建议始终提供"
          },
          "PositionTicks": {
            "type": "integer",
            "format": "int64",
            "description": "播放时间单位：10,000,000 ticks = 1 秒。",
            "example": 600000000,
            "minimum": 0
          },
          "IsPaused": {
            "type": "boolean",
            "description": "是否暂停"
          }
        },
        "required": [
          "ItemId",
          "PlaySessionId"
        ]
      },
      "ServerInfo": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string"
          },
          "ServerName": {
            "type": "string",
            "example": "Drivemby"
          },
          "Version": {
            "type": "string",
            "description": "Emby 兼容版本"
          },
          "OperatingSystem": {
            "type": "string"
          },
          "LocalAddress": {
            "type": "string",
            "nullable": true
          },
          "WanAddress": {
            "type": "string"
          },
          "ProductName": {
            "type": "string"
          },
          "StartupWizardCompleted": {
            "type": "boolean",
            "description": "初始化完成"
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "description": "媒体 ID"
          },
          "Name": {
            "type": "string",
            "description": "作品名称"
          },
          "Type": {
            "type": "string",
            "enum": [
              "CollectionFolder",
              "Movie",
              "BoxSet",
              "Series",
              "Season",
              "Episode",
              "Video",
              "Folder"
            ]
          },
          "IsFolder": {
            "type": "boolean",
            "description": "是否可包含子条目"
          },
          "ServerId": {
            "type": "string"
          },
          "ParentId": {
            "type": "string"
          },
          "CollectionType": {
            "type": "string",
            "enum": [
              "movies",
              "tvshows",
              "boxsets",
              "folders"
            ],
            "description": "分类媒体库类型"
          },
          "SortName": {
            "type": "string"
          },
          "Overview": {
            "type": "string",
            "description": "简介"
          },
          "ProductionYear": {
            "type": "integer",
            "format": "int64",
            "description": "年份",
            "example": 2025
          },
          "PremiereDate": {
            "type": "string",
            "format": "date-time"
          },
          "DateCreated": {
            "type": "string",
            "format": "date-time"
          },
          "RunTimeTicks": {
            "type": "integer",
            "format": "int64",
            "description": "播放时间单位：10,000,000 ticks = 1 秒。",
            "example": 600000000,
            "minimum": 0
          },
          "ProviderIds": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "Tmdb": "157744"
            }
          },
          "Genres": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "Studios": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "Id": {
                  "type": "string"
                },
                "Name": {
                  "type": "string"
                }
              }
            }
          },
          "ImageTags": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "BackdropImageTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "SeriesId": {
            "type": "string"
          },
          "SeriesName": {
            "type": "string"
          },
          "SeasonId": {
            "type": "string"
          },
          "SeasonName": {
            "type": "string"
          },
          "ParentIndexNumber": {
            "type": "integer",
            "format": "int64",
            "description": "集所属季号",
            "example": 1
          },
          "IndexNumber": {
            "type": "integer",
            "format": "int64",
            "description": "季号或集号",
            "example": 1
          },
          "IndexNumberEnd": {
            "type": "integer",
            "format": "int64",
            "description": "多集合并文件的结束集号"
          },
          "ChildCount": {
            "type": "integer",
            "format": "int64"
          },
          "ParentLogoItemId": {
            "type": "string"
          },
          "ParentLogoImageTag": {
            "type": "string"
          },
          "ParentBackdropItemId": {
            "type": "string"
          },
          "ParentBackdropImageTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "SeriesPrimaryImageTag": {
            "type": "string"
          },
          "UserData": {
            "$ref": "#/components/schemas/UserData"
          },
          "MediaSources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MediaSource"
            }
          },
          "Images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Image"
            },
            "description": "Drivemby 扩展：仅详情接口返回完整图片候选；无需额外图片列表接口"
          }
        }
      },
      "ItemList": {
        "type": "object",
        "properties": {
          "Items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "TotalRecordCount": {
            "type": "integer",
            "format": "int64",
            "description": "筛选后总条数，不是当前页条数",
            "example": 120
          }
        }
      },
      "HistoryEntry": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "description": "历史记录 ID，删除时使用此 ID"
          },
          "ItemId": {
            "type": "string",
            "description": "媒体 ID；媒体删除后仍保留历史"
          },
          "Name": {
            "type": "string",
            "description": "播放时保存的作品名"
          },
          "MediaSourceId": {
            "type": "string",
            "nullable": true
          },
          "SourceName": {
            "type": "string",
            "description": "文件名",
            "nullable": true
          },
          "Client": {
            "type": "string",
            "nullable": true
          },
          "DeviceName": {
            "type": "string",
            "nullable": true
          },
          "StartedAt": {
            "type": "string",
            "format": "date-time"
          },
          "StoppedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "PlaybackPositionTicks": {
            "type": "integer",
            "format": "int64",
            "description": "播放时间单位：10,000,000 ticks = 1 秒。",
            "example": 600000000,
            "minimum": 0
          },
          "RunTimeTicks": {
            "type": "integer",
            "format": "int64",
            "description": "播放时间单位：10,000,000 ticks = 1 秒。",
            "example": 600000000,
            "minimum": 0,
            "nullable": true
          },
          "Completed": {
            "type": "boolean",
            "description": "本次播放是否完成"
          },
          "PlayedPercentage": {
            "type": "number",
            "description": "有可信时长时返回"
          }
        }
      },
      "HistoryList": {
        "type": "object",
        "properties": {
          "Items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoryEntry"
            }
          },
          "TotalRecordCount": {
            "type": "integer",
            "format": "int64",
            "description": "符合搜索的历史总数"
          },
          "NextCursor": {
            "type": "string",
            "description": "下一页游标；无更多时为 null",
            "nullable": true
          }
        }
      },
      "MediaSourceOrigin": {
        "type": "object",
        "properties": {
          "Drive": {
            "type": "string",
            "description": "网盘类型",
            "example": "115 网盘"
          },
          "Directory": {
            "type": "string",
            "description": "文件所在目录（从网盘根目录起，不含文件名）；目录信息暂缺时不返回",
            "example": "/电影/阿凡达 (2009)"
          },
          "FileName": {
            "type": "string",
            "description": "文件名",
            "example": "Avatar.2009.2160p.BluRay.REMUX.mkv"
          }
        }
      }
    }
  }
}