AutoBangumi REST API 参考：从认证鉴权到番剧自动化管理的完整集成指南

• 后端
• 前端
• 音视频

【免费下载链接】Auto_Bangumi

AutoBangumi - 全自动追番工具

项目地址：https://gitcode.com/gh_mirrors/au/Auto_Bangumi

点击查看免费下载

AutoBangumi 在http://your-host:7892/api/v1下暴露了一套完整的 REST API，覆盖账号认证、Passkey 无密码登录、番剧下载规则（Bangumi）、RSS 订阅、种子下载管理、程序生命周期控制与首轮初始化向导等全部核心能力。本文以 官方 API 参考 为骨架，结合 backend/src/module/api 目录下的真实路由实现，逐组讲解每个端点的请求方式、请求体、响应语义与底层调用链，帮助你在命令行、脚本、Home Assistant / cron 等外部自动化场景中可靠地调用 AutoBangumi。

概览：Base URL、认证与交互式文档

所有业务端点统一挂载在/api/v1前缀之下（见 main.py 的app.include_router(v1, prefix="/api")），默认监听端口为7892（由settings.program.webui_port控制，见 main.py）。

• Base URL：http://your-host:7892/api/v1
• 认证方式：除login、setup相关端点外，其余端点均要求携带 JWT 令牌，可通过Cookie: token=<jwt>或Authorization: Bearer <token>请求头传入。
• 交互式文档：开发模式下访问http://your-host:7892/docs可打开 Swagger UI 在线调试（VERSION == "DEV_VERSION"时根路径/会 302 重定向到/docs，见 main.py）。

值得注意的是，还有两个不需要认证的端点并不属于/api/v1前缀：GET /health存活探针（供 Docker HEALTHCHECK 等外部探针使用，返回{"status": "ok", "version": VERSION, "db_ok": bool}，见 health.py），以及挂载在/mcp下的 MCP SSE 服务（用于 LLM 工具集成）。

统一响应格式与错误语义

除流式（SSE）和列表类端点外，绝大多数写操作的响应遵循统一格式（对应 response.py 中的APIResponse模型）：

{ "msg_en": "Success message in English", "msg_zh": "Success message in Chinese", "status": true }

部分端点（如批量操作）还会返回status_code字段（ResponseModel，见 models/response.py）。错误响应使用标准 HTTP 状态码（400、401、403、404、500 等），并同时包含中英双语错误信息。例如配置更新失败时返回 406，掩码密钥无法恢复时返回 400，见 config.py。

认证（Authentication）

认证路由定义在 auth.py，前缀为/auth，基于数据库持久化会话（AuthenticationService）。登录成功后会在响应中通过Set-Cookie写入token，httponly=True、samesite="strict"、有效期 86400 秒（见_issue_session，auth.py）。

登录

POST /auth/login

以用户名密码认证（表单格式，OAuth2PasswordRequestForm）。请求体示例：

{ "username": "string", "password": "string" }

成功后在响应中设置携带 JWT 的认证 Cookie；密码错误返回 401。注意该端点受check_login_ip依赖保护（见 auth.py）。

刷新令牌

POST /auth/refresh_token

刷新当前认证令牌以延长会话。源码中该端点以POST为推荐方法（auth.py），同时保留了GET /auth/refresh_token作为**已废弃（deprecated）**的兼容别名（会返回Deprecation响应头，提示改用 POST，见 auth.py）。官方文档中标注的GET形式在新版本中仍可用，但新集成请一律使用 POST。

登出

POST /auth/logout

注销当前持久化会话并清除 Cookie（response.delete_cookie(key="token", ...)）。官方文档标注为GET /auth/logout，当前实现同时兼容。

更新凭据

POST /auth/update

更新当前账号的用户名和/或密码，成功后轮换该用户的所有会话并重新签发令牌。需要浏览器会话（SessionPrincipal），请求体：

{ "username": "string", "password": "string" }

字段可只传需要修改的部分（model_dump(exclude_unset=True)），用户不存在返回 404、用户名冲突返回 409（auth.py）。

Passkey / WebAuthn 无密码认证（v3.2+）

路由定义在 passkey.py，前缀为/passkey，基于 WebAuthn/FIDO2 实现无密码登录。WebAuthn 的rp_id与origin优先读取settings.security.webauthn_rp_id / webauthn_origin；未配置时从请求头推断（Origin → Referer → Host），反向代理场景下建议显式配置以防请求头伪造（见_get_webauthn_from_request，passkey.py）。

注册 Passkey

POST /passkey/register/options POST /passkey/register/verify

第一个端点返回 WebAuthn 注册选项（challenge、relying party 信息），前端配合navigator.credentials.create()使用；第二个端点验证浏览器的注册响应（attestation_response）并持久化保存凭证。需要浏览器会话。注册验证失败（如 challenge 不匹配）返回 400。

使用 Passkey 认证

POST /passkey/auth/options POST /passkey/auth/verify

/auth/options生成认证 challenge：传入username时返回该用户的allowCredentials列表（按用户名模式）；不传时生成可发现凭证选项（浏览器展示所有可用 Passkey）。为防止用户名枚举，用户名不存在或没有注册 Passkey 时返回相同的 400 文案（passkey.py）。

/auth/verify验证认证响应并通过issue_session_for_verified_passkey签发 JWT 会话 Cookie（有效期同样为 86400 秒），替代密码登录（passkey.py）。

管理 Passkey

GET /passkey/list POST /passkey/delete

/list返回当前用户全部已注册 Passkey 列表；/delete按passkey_id删除指定凭证。两者均需浏览器会话，删除时校验凭证归属当前用户（passkey.py）。

配置（Configuration）

路由定义在 config.py，前缀为/config。

获取配置

GET /config/get

返回完整配置对象，包含program、downloader、rss_parser、bangumi_manager、notification、proxy、experimental_openai（LLM 解析器相关）等全部区块。敏感字段自动脱敏：键名包含password、api_key、token、secret的字符串值会被递归替换为********（_sanitize_dict，config.py）。

更新配置

PATCH /config/update

部分更新配置，请求体为配置对象的部分字段，只传需要修改的项。底层流程（config.py）：

1. 通过_restore_masked将请求中的********掩码值恢复为当前已保存的真实值——列表项（如通知渠道）按非敏感字段身份匹配，无法唯一定位来源时返回 400 并提示重新输入密钥，绝不猜测（MaskRestoreError）；
2. settings.save()落盘（同步文件 I/O 通过asyncio.to_thread移出事件循环）；
3. ctx.reload_settings()从磁盘重载配置，重建共享 HTTP 客户端、通知器与 RSS/重命名循环。

另有一个文档之外但 WebUI 依赖的辅助端点POST /config/llm/models：按提供商拉取 LLM 可用模型列表，表单中的密钥若为掩码则回退到已保存值（config.py）。

番剧规则（Bangumi / Anime Rules）

路由定义在 bangumi.py，前缀为/bangumi，是管理"追番下载规则"的核心 API，底层由TorrentManager与Database支撑。

查询

GET /bangumi/get/all # 获取全部番剧下载规则 GET /bangumi/get/{bangumi_id} # 按 ID 获取单条规则

修改与删除

PATCH /bangumi/update/{bangumi_id} # 更新规则元数据（标题、季度、集数偏移等） DELETE /bangumi/delete/{bangumi_id} # 删除单条规则及其关联种子 POST /bangumi/delete/many/ # 批量删除

批量删除请求体：

{ "bangumi_ids": [1, 2, 3] }

批量端点还有可选的file布尔查询参数控制是否同时删除下载文件，并通过_aggregate_response返回"已删除 n/m 条规则"的中英双语汇总（bangumi.py）。路由注册顺序保证many字面量不会被当作 ID 捕获。

禁用 / 启用

DELETE /bangumi/disable/{bangumi_id} # 禁用规则（保留文件，停止下载） POST /bangumi/disable/many # 批量禁用 POST /bangumi/enable/{bangumi_id} # 重新启用

官方文档将禁用/启用标注为 DELETE / GET，当前源码实现为 POST（兼容历史调用方式，同时注册了对应别名）；批量端点同样支持file参数。

海报与日历刷新

GET /bangumi/refresh/poster/all # 从 TMDB 刷新全部番剧海报 GET /bangumi/refresh/poster/{bangumi_id} # 刷新单部番剧海报 GET /bangumi/refresh/calendar # 从 Bangumi.tv 刷新放送日历 GET /bangumi/refresh/metadata # 刷新 TMDB 元数据并自动归档完结番剧

海报通过TorrentManager.refresh_poster() / refind_poster()实现，静态资源由/posters/{path}路由提供（带路径穿越防护，见 main.py）。

重置

POST /bangumi/reset/all

删除全部番剧规则（db.bangumi.delete_all()），官方文档标注为 GET，源码为 POST。此操作不可恢复，请谨慎调用。

偏移量相关（番剧集数偏差修正）

源码中还包括一组与偏移量（offset）修正相关的端点，用于解决集数编号不一致问题：

• POST /bangumi/detect-offset：提交{"title", "parsed_season", "parsed_episode"}，结合 TMDB 数据检测季度/集数偏差，返回has_mismatch、suggestion（含season_offset、episode_offset、reason、confidence）与 TMDB 摘要（bangumi.py）；
• POST /bangumi/apply-offset/{bangumi_id}与POST /bangumi/apply-offset/many：应用建议偏移并立即触发一轮重命名（_trigger_rename）；
• GET /bangumi/needs-review：列出待用户确认偏移的番剧；POST /bangumi/dismiss-review/{bangumi_id}：清除待复查标记；
• GET /bangumi/suggest-offset/{bangumi_id}：基于 TMDB 集数给出偏移建议；
• PATCH /bangumi/{bangumi_id}/weekday：手动设置放送日（0-6 表示周一至周日，null 表示清除）。

种子关联与孤儿种子（v3.2+）

• GET /{bangumi_id}/torrents/DELETE /{bangumi_id}/torrents：列出 / 删除某番剧下所有种子记录；
• GET /torrents/orphans、GET /torrents/orphans/count、DELETE /torrents/orphans：查看、计数、清空未关联任何番剧的孤儿种子记录；
• DELETE /torrents/orphans/{torrent_id}：删除单条孤儿种子。

孤儿种子路径使用字面量注册在/{bangumi_id}/torrents之前，避免路由歧义（bangumi.py）。

RSS 订阅（RSS Feeds）

路由定义在 rss.py，前缀为/rss，底层由RSSEngine、RSSAnalyser、DownloadClient协同工作。

查询与增删改

GET /rss # 获取全部已配置 RSS 源 POST /rss/add # 新增订阅 POST /rss/enable/many # 批量启用 PATCH /rss/disable/{rss_id} # 禁用单个 POST /rss/disable/many # 批量禁用 DELETE /rss/delete/{rss_id} # 删除单个 POST /rss/delete/many # 批量删除 PATCH /rss/update/{rss_id} # 更新配置

新增订阅请求体：

{ "url": "string", "aggregate": true, "parser": "mikan" }

parser的合法取值为mikan、tmdb、parser（常量PARSER_TYPES，rss.py）。

刷新与种子查询

POST /rss/refresh/all # 手动触发全部 RSS 源刷新 POST /rss/refresh/{rss_id} # 刷新单个 RSS 源 GET /rss/torrent/{rss_id} # 获取某 RSS 源解析出的种子列表

注意：官方文档中/rss/refresh/*标注为 GET，当前源码为 POST（@router.post，见 rss.py）。刷新流程在async with DownloadClient()上下文中执行engine.refresh_rss()，即拉取 RSS → 解析 → 匹配番剧规则 → 下发种子到下载器。

分析与订阅

POST /rss/analysis # 分析 RSS URL 并提取番剧元数据（不订阅） POST /rss/collect # 下载 RSS 源全部剧集（用于已完结番剧补全） POST /rss/subscribe # 订阅 RSS 源，开启自动追更下载

• /analysis通过RSSAnalyser.link_to_data()返回Bangumi | Movie结构化结果；
• /collect通过SeasonCollector.collect_season()整季收集；
• /subscribe会处理一个关键兼容细节：前端搜索订阅时传来的可能是站点名（nyaa/dmhy），需要按搜索源配置把站点名映射为解析器类型；已是解析器类型的值（如mikan）原样透传、不参与映射，避免与同名站点混淆（rss.py）。

搜索（Search）

路由定义在 search.py，前缀为/search。

搜索番剧种子（SSE 实时流）

GET /search/bangumi?keyword={keyword}&provider={provider}

查询参数：

• keyword— 搜索关键词，多个关键词以空格分隔（keywords.split(" ")）
• provider— 搜索源（如mikan、nyaa、dmhy）

返回Server-Sent Events（SSE）流，实时推送解析后的搜索结果（EventSourceResponse），由SearchTorrent.analyse_keyword()逐条产出。适合 WebUI 的实时搜索面板场景，前端用EventSource或fetch流式读取。

搜索源管理

GET /search/provider # 可用搜索源列表 GET /search/provider/config # 各搜索源 URL 模板 PUT /search/provider/config # 更新搜索源配置（dict[str, str]）

注意：官方文档只列出provider端点，源码中provider/config的 GET/PUT 对用于读写各搜索源的 URL 模板（内部保存为{url, parser}，对外只暴露 URL），见 search.py。

程序控制（Program Control）

路由定义在 program.py，当前推荐方法为 POST，同时为 3.2 及更早版本的自动化脚本（cron / Home Assistant）保留了GET 兼容别名（标记为 deprecated，计划下个大版本移除，见 program.py）。

POST /status # 获取状态（status / version / first_run） POST /start # 启动主程序（RSS 检查、下载、重命名） POST /restart # 重启主程序 POST /stop # 停止主程序（WebUI 仍可访问） POST /shutdown # 关闭整个应用（容器环境将触发重启） POST /check/downloader # 测试下载器（qBittorrent）连通性

/status响应：

{ "status": "running", "version": "3.2.0", "first_run": false }

源码实现中status为布尔值（ctx.is_running），version取自VERSION常量，first_run反映是否为首次启动。/shutdown在停止任务后向自身进程发送SIGINT（program.py）；/check/downloader返回布尔连通性结果（ctx.check_downloader()）。

下载器管理（Downloader Management，v3.2+）

路由定义在 downloader.py，前缀为/downloader，允许直接通过 AutoBangumi 管理下载器（qBittorrent）中的种子。

GET /downloader/torrents # 获取 Bangumi 分类下全部种子 POST /downloader/torrents/pause # 按 hash 暂停 POST /downloader/torrents/resume # 按 hash 恢复 POST /downloader/torrents/delete # 删除（可选同时删文件）

暂停 / 恢复 / 删除的请求体：

{ "hashes": ["hash1", "hash2"] }

删除可选delete_files：

{ "hashes": ["hash1", "hash2"], "delete_files": false }

源码中将多个 hash 以|拼接后调用下载器客户端的pause_torrent / resume_torrent / delete_torrent（downloader.py）。

源码中另有与 WebUI 相关的扩展端点：

• POST /downloader/torrents/tag：为种子打上ab:{bangumi_id}标签，供重命名器准确查找季度/集数偏移；
• POST /downloader/torrents/tag/auto：按名称/保存路径自动匹配并补打标签（修复标签功能上线前的旧种子），返回tagged_count与未匹配列表；
• GET /downloader/rename-conflicts与POST /downloader/rename-conflicts/{operation_id}/retry：列出 / 清除持久化重命名冲突，供重命名下一轮重新校验（downloader.py）。

首次启动向导（Setup Wizard，v3.2+）

路由定义在 setup.py，前缀为/setup。仅在首次启动、初始化向导未完成时可访问，且不需要认证；向导完成后（创建哨兵文件config/.setup_complete），所有端点返回403 Forbidden（_require_setup_needed守卫，setup.py）。

GET /setup/status # 检查是否需要初始化 POST /setup/test-downloader # 测试下载器连接 POST /setup/test-rss # 验证 RSS 源可访问可解析 POST /setup/test-notification # 发送测试通知 POST /setup/complete # 保存配置并标记完成

/setup/status响应：

{ "need_setup": true }

need_setup的判断逻辑：开发模式下仅看哨兵文件是否存在；正式版本还需配置仍为出厂默认值（settings.dict() == Config().dict()，见 setup.py）。

/setup/test-downloader请求体：

{ "type": "qbittorrent", "host": "172.17.0.1:8080", "username": "admin", "password": "adminadmin", "ssl": false }

底层实现值得注意的细节：

• 支持aria2类型（走 JSON-RPCaria2.getVersion验证可达性与 RPC secret）与开发用的mock类型；
• qBittorrent 验证会依次检查首页特征文本、调用/api/v2/auth/login，兼容 qBittorrent < 5.2 的 200 + "Ok." 与 ≥ 5.2 的 204 空响应两种登录成功形态（setup.py）；
• 这是预认证端点，错误详情只写服务端日志，不向客户端回显原始异常（setup.py）。

/setup/test-rss请求体：

{ "url": "https://mikanime.tv/RSS/MyBangumi?token=xxx" }

该端点会拒绝非 http/https scheme 以及指向私网/保留/回环 IP 的 URL（_validate_url，SSRF 防护，setup.py）；解析成功后返回频道标题与 item 数量。

/setup/test-notification请求体：

{ "type": "telegram", "token": "bot_token", "chat_id": "chat_id" }

通过PROVIDER_REGISTRY查找通知提供商并调用其test()发送测试消息，未知类型返回失败（setup.py）。

/setup/complete接收完整配置对象（SetupCompleteRequest），一次性完成四件事：

1. 更新管理员账号凭据并作废所有预初始化会话（若默认密码已被改过，则要求调用方已具备有效会话，防止未授权覆盖真实凭据，_require_default_admin_or_authenticated，setup.py）；
2. 写入 downloader 配置（类型、host、账号、保存路径，默认/downloads/Bangumi）及可选的通知配置，settings.save()落盘后经ctx.reload_settings()重建运行时组件；
3. 若提供了rss_url则调用RSSEngine.add_rss()添加初始订阅；
4. 创建哨兵文件config/.setup_complete并启动后台任务。

日志（Logs）

GET /log # 获取完整应用日志文件 GET /log/clear # 清空日志文件

两个端点均需认证，便于自动化排查与日志轮转。

实战建议与兼容性提示

将官方文档与 backend/src/module/api 源码对照后，可以整理出几条对自动化集成至关重要的兼容性结论：

1. 方法以源码为准：文档中部分端点标注的 HTTP 方法（如/auth/refresh_token的 GET、/rss/refresh/*的 GET、/bangumi/disable的 DELETE、/bangumi/enable的 GET、程序控制的 GET）在较新版本中已迁移为 POST；为保持老脚本可用，多数端点保留了 GET 兼容别名（标记 deprecated），但新集成应优先采用 POST 形态。
2. 认证两种形态：WebUI 走 Cookie 会话；脚本/CLI 集成可调用POST /auth/login后用Authorization: Bearer <token>头访问其他端点。
3. 配置写入注意掩码语义：GET /config/get会把密钥掩码为********，PATCH /config/update提交时这些掩码值会被原样恢复；若列表项被删除/重排导致无法唯一定位来源，会返回 400 要求重新输入密钥——这是刻意的安全设计，防止密钥被静默写坏。
4. 批量操作返回聚合结果：/bangumi/delete/many、/bangumi/disable/many、/rss/disable/many等返回已操作 n/m 条的双语汇总，全部成功为 200，部分失败为 500。
5. 预认证端点自带 SSRF 防护：/setup/test-rss拒绝私网地址，/setup/test-downloader仅允许 http/https scheme——集成脚本传入 URL 时需注意。

如果你需要完整的请求/响应契约细节（字段校验、默认值、响应模型），开发模式下可访问http://your-host:7892/docs的 Swagger UI 在线调试；生产环境则建议直接参考 backend/src/module/api 下各路由文件与 backend/src/module/models/api.py 中的 Pydantic 模型，它们才是当前版本 API 契约的最终事实来源。

赞分享

• 后端
• 前端
• 音视频

【免费下载链接】Auto_Bangumi

AutoBangumi - 全自动追番工具

项目地址：https://gitcode.com/gh_mirrors/au/Auto_Bangumi

点击查看免费下载

相关推荐

• AutoBangumi REST API 完全指南：从认证、番剧规则到下载器管理的全端点实战

  AutoBangumi REST API 完全指南：从认证、番剧规则到下载器管理的全端点实战 AutoBangumi 以 /api/v1 为前缀对外提供一套完整

  后端前端音视频

• CyberStrikeAI API 参考指南：从 OpenAPI 文档、认证鉴权到资产批量导入的完整集成手册

  CyberStrikeAI API 参考指南：从 OpenAPI 文档、认证鉴权到资产批量导入的完整集成手册 CyberStrikeAI 是一套以 AI 原生安

  网络安全渗透测试人工智能大模型AI AgentRAG后端前端MCP 服务漏洞扫描

• Apache Zeppelin REST API完整参考：自动化管理与集成开发

  Apache Zeppelin REST API完整参考：自动化管理与集成开发 Apache Zeppelin REST API 是数据分析和协作开发的强大工具

  数据分析数据可视化大数据后端

上一篇：ParadeDB JoinScan 实战：用 BM25 分数排序驱动带权限过滤的 JOIN 查询（join_permissioned_search）

下一篇：5分钟搞定ESP32：告别复杂配置，轻松开启物联网开发之旅