概览

这组文档覆盖个人记录页使用的接口，全部挂在 /api/account/records。 这些接口既可以在站内登录态下调用，也可以让外部脚本或客户端通过个人 API Key 调用。

所有成功响应都使用统一格式：{ "rcode": 0, "msg": "ok", ...payload }； 失败响应则返回非 0 的 rcode 与错误信息 msg。

/account/records 的首屏第一页会在服务端完成渲染，用于更快展示默认记录列表； 用户切换记录类型、翻页、搜索、补录或删除后，前端会继续通过这些接口刷新数据。

认证

支持两种认证方式：

  • 站内登录态：浏览器已登录时，直接请求即可。
  • 个人 API Key：在请求头里传 Authorization: Bearer <your-api-key>。
http
Authorization: Bearer mjav_xxxxxxxxxxxxxxxxx

如果既没有登录态，也没有提供有效的 Bearer Token，接口会返回 4010； 如果 Token 无效，则返回 4011。

查询个人记录

分页读取当前用户某个记录类型下的记录，或者在提交搜索后返回跨记录类型的搜索结果列表。

对应接口：GET /api/account/records

tagstring条件必填传入 `watch_later`、`favorite` 或 `dislike` 时，分页读取对应记录类型
pagenumber否页码，默认 1
pageSizenumber否每页数量，默认 100
querystring条件必填提交后进入搜索结果列表；不传时按 `tag` 读取
bash
curl '/api/account/records?tag=favorite&page=1&pageSize=50' \
  -H 'Authorization: Bearer mjav_xxxxxxxxxxxxxxxxx'

curl '/api/account/records?page=1&pageSize=50&query=SSIS' \
  -H 'Authorization: Bearer mjav_xxxxxxxxxxxxxxxxx'
json
{
  "rcode": 0,
  "msg": "ok",
  "tag": "favorite",
  "page": 1,
  "pageSize": 50,
  "total": 2,
  "totalPages": 1,
  "entries": [
    {
      "code": "SSIS-123",
      "tag": "favorite",
      "createdAt": "2026-05-30T13:30:00.000Z",
      "updatedAt": "2026-05-30T13:40:00.000Z"
    }
  ]
}

批量补录个人记录

批量为某个记录类型补录记录。请求体接收记录类型和一段原始文本，服务端会自行提取有效番号。

对应接口：POST /api/account/records

tagstring是要补录到的记录类型，可选 `watch_later`、`favorite`、`dislike`
codesTextstring是支持多行、多空格或夹杂普通文本的原始输入
bash
curl '/api/account/records' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mjav_xxxxxxxxxxxxxxxxx' \
  -d '{"tag":"dislike","codesText":"SSIS-123\nMIDE-456\nrandom text"}'
json
{
  "rcode": 0,
  "msg": "ok",
  "tag": "dislike",
  "insertedCount": 2,
  "skippedExistingCount": 1,
  "skippedDuplicateInputCount": 0,
  "invalidCount": 1
}

当请求体里提取不到任何有效番号时，接口返回 4001。

移除个人记录项

删除单条记录项，也就是移除某个“番号 + 记录类型”的私有状态。

对应接口：DELETE /api/account/records

codestring是要移除标签的番号
tagstring是要移除的记录类型，可选 `watch_later`、`favorite`、`dislike`
bash
curl '/api/account/records' \
  -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mjav_xxxxxxxxxxxxxxxxx' \
  -d '{"code":"SSIS-123","tag":"dislike"}'
json
{
  "rcode": 0,
  "msg": "ok"
}

错误返回

常见错误码如下：

番号详情接口会先保存源站原始详情，再生成中文详情；如果原始详情已取得但中文本地化失败，接口会返回原文 fallback 和本地化缺失状态，而不是把整次请求作为 5000。

4000参数中的 `tag` 不合法
4001导入时没有解析出任何有效番号
4002分页参数无效
4003删除时 `code` 为空
4010未登录且未提供个人 API Key
4011个人 API Key 无效
5000服务端内部错误
json
{
  "rcode": 4011,
  "msg": "个人 API key 无效，请前往账户页重新生成。"
}