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

后端前端音视频【免费下载链接】Auto_BangumiAutoBangumi - 全自动追番工具项目地址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 URLhttp://your-host:7892/api/v1认证方式除login、setup相关端点外其余端点均要求携带 JWT 令牌可通过Cookie: tokenjwt或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写入tokenhttponlyTrue、samesitestrict、有效期 86400 秒见_issue_sessionauth.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注销当前持久化会话并清除 Cookieresponse.delete_cookie(keytoken, ...)。官方文档标注为GET /auth/logout当前实现同时兼容。更新凭据POST /auth/update更新当前账号的用户名和/或密码成功后轮换该用户的所有会话并重新签发令牌。需要浏览器会话SessionPrincipal请求体{ username: string, password: string }字段可只传需要修改的部分model_dump(exclude_unsetTrue)用户不存在返回 404、用户名冲突返回 409auth.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_requestpasskey.py。注册 PasskeyPOST /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。管理 PasskeyGET /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_openaiLLM 解析器相关等全部区块。敏感字段自动脱敏键名包含password、api_key、token、secret的字符串值会被递归替换为********_sanitize_dictconfig.py。更新配置PATCH /config/update部分更新配置请求体为配置对象的部分字段只传需要修改的项。底层流程config.py通过_restore_masked将请求中的********掩码值恢复为当前已保存的真实值——列表项如通知渠道按非敏感字段身份匹配无法唯一定位来源时返回 400 并提示重新输入密钥绝不猜测MaskRestoreErrorsettings.save()落盘同步文件 I/O 通过asyncio.to_thread移出事件循环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.pyPOST /bangumi/apply-offset/{bangumi_id}与POST /bangumi/apply-offset/many应用建议偏移并立即触发一轮重命名_trigger_renameGET /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.2GET /{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_TYPESrss.py。刷新与种子查询POST /rss/refresh/all # 手动触发全部 RSS 源刷新 POST /rss/refresh/{rss_id} # 刷新单个 RSS 源 GET /rss/torrent/{rss_id} # 获取某 RSS 源解析出的种子列表注意官方文档中/rss/refresh/*标注为 GET当前源码为 POSTrouter.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 EventsSSE流实时推送解析后的搜索结果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_runningversion取自VERSION常量first_run反映是否为首次启动。/shutdown在停止任务后向自身进程发送SIGINTprogram.py/check/downloader返回布尔连通性结果ctx.check_downloader()。下载器管理Downloader Managementv3.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_torrentdownloader.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 Wizardv3.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?tokenxxx }该端点会拒绝非 http/https scheme 以及指向私网/保留/回环 IP 的 URL_validate_urlSSRF 防护setup.py解析成功后返回频道标题与 item 数量。/setup/test-notification请求体{ type: telegram, token: bot_token, chat_id: chat_id }通过PROVIDER_REGISTRY查找通知提供商并调用其test()发送测试消息未知类型返回失败setup.py。/setup/complete接收完整配置对象SetupCompleteRequest一次性完成四件事更新管理员账号凭据并作废所有预初始化会话若默认密码已被改过则要求调用方已具备有效会话防止未授权覆盖真实凭据_require_default_admin_or_authenticatedsetup.py写入 downloader 配置类型、host、账号、保存路径默认/downloads/Bangumi及可选的通知配置settings.save()落盘后经ctx.reload_settings()重建运行时组件若提供了rss_url则调用RSSEngine.add_rss()添加初始订阅创建哨兵文件config/.setup_complete并启动后台任务。日志LogsGET /log # 获取完整应用日志文件 GET /log/clear # 清空日志文件两个端点均需认证便于自动化排查与日志轮转。实战建议与兼容性提示将官方文档与 backend/src/module/api 源码对照后可以整理出几条对自动化集成至关重要的兼容性结论方法以源码为准文档中部分端点标注的 HTTP 方法如/auth/refresh_token的 GET、/rss/refresh/*的 GET、/bangumi/disable的 DELETE、/bangumi/enable的 GET、程序控制的 GET在较新版本中已迁移为 POST为保持老脚本可用多数端点保留了 GET 兼容别名标记 deprecated但新集成应优先采用 POST 形态。认证两种形态WebUI 走 Cookie 会话脚本/CLI 集成可调用POST /auth/login后用Authorization: Bearer token头访问其他端点。配置写入注意掩码语义GET /config/get会把密钥掩码为********PATCH /config/update提交时这些掩码值会被原样恢复若列表项被删除/重排导致无法唯一定位来源会返回 400 要求重新输入密钥——这是刻意的安全设计防止密钥被静默写坏。批量操作返回聚合结果/bangumi/delete/many、/bangumi/disable/many、/rss/disable/many等返回已操作 n/m 条的双语汇总全部成功为 200部分失败为 500。预认证端点自带 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_BangumiAutoBangumi - 全自动追番工具项目地址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告别复杂配置轻松开启物联网开发之旅创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考