qBittorrent 如何用 WebUI API 创建种子任务并跟踪制作状态【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent如果你想在脚本或自动化流程里把服务器上的某个文件夹打包成 .torrent 文件而不是打开 WebUI 点按钮qBittorrent 的 WebUI API 提供了torrentcreator这一组接口提交一个制作任务、轮询任务状态、最后把生成好的 .torrent 文件下载下来。整个过程只需要 HTTP 请求适用于 headless 部署和批处理场景。本文的操作对象是 qBittorrent WebUI 的 REST API所有接口都挂在/api/v2/前缀下见 webapplication.cpp 中的API_PATH定义。前提是你的 qBittorrent 实例已经开启了 WebUIGUI 版在选项里启用 WebUI或运行带 WebUI 的 nox 版本并且你知道 WebUI 的用户名、密码以及监听的端口。下文中http://host:port请替换为你实际的 WebUI 地址和端口。四个 torrentcreator 端点与参数torrentcreator控制器注册了 4 个 actiontorrentcreatorcontroller.cpp端点作用关键参数torrentcreator/addTask提交种子制作任务sourcePath必填torrentFilePathformatpieceSizeprivateignoreDotfilescommentsourcetrackersurlSeedsstartSeedingtorrentcreator/status查询任务状态taskID可选省略时返回所有任务torrentcreator/torrentFile下载已完成的 .torrent 文件taskID必填torrentcreator/deleteTask删除任务taskID必填addTask参数的几个要点均取自控制器源码的解析逻辑sourcePath是唯一必填参数必须能被 qBittorrent 进程访问到本地文件系统路径。torrentFilePath指定 .torrent 文件的保存位置。注意startSeeding参数的行为未提供torrentFilePath时默认值为true制作完成后会直接把内容加入会话开始做种提供了torrentFilePath时默认为false即只生成文件、不做种。trackers和urlSeeds都是多个 URL 的列表传输时用管道符|分隔每个 URL 需做百分号编码如https%3A%2F%2F...空行表示 tracker 分层。ignoreDotfiles默认true忽略点文件private默认false。使用 libtorrent 2 构建的版本用format参数选择种子格式可选v1、v2或不传默认hybrid旧构建则使用optimizeAlignment和paddedFileSizeLimit参数二者不会同时存在。第一步登录取得会话auth/login是唯一公开无需鉴权的端点其余 API 都需要有效会话。两种方式任选其一方式一Cookie 会话。POST 请求带上 Basic 认证成功后响应里会返回SIDcookie后续请求携带它即可curl -c cookies.txt -X POST http://host:port/api/v2/auth/login \ --user username:password把 WebUI 用户名密码替换进--user。-c把会话 cookie 存到cookies.txt后续请求加-b cookies.txt复用。方式二API Key 会话可选分支。先生成一个 API keycurl -b cookies.txt -X POST http://host:port/api/v2/app/rotateAPIKey响应是 JSON形如{apiKey: ...}取出apiKey字段后之后的请求改用Authorization: Bearer apiKey头即可不再依赖 cookie。注意使用 API key 会话时调用任何auth/*端点都会被拒绝返回 403登录只能靠 cookie 完成。第二步提交种子制作任务向addTask发送POST表单请求。以把/data/releases/ubuntu-24.04打包成私有种子、保存为/data/out/ubuntu.torrent为例curl -b cookies.txt -X POST http://host:port/api/v2/torrentcreator/addTask \ -d sourcePath/data/releases/ubuntu-24.04 \ -d torrentFilePath/data/out/ubuntu.torrent \ -d privatetrue \ -d formatv1 \ -d trackershttps%3A%2F%2Ftracker.example.com%2Fannounce成功时响应是 JSON{taskID: 1}记下taskID后续轮询和下载都靠它。如果服务端提示任务数过多Too many active tasks请求会返回 409 冲突错误此时需要先等待已有任务完成或先deleteTask清理再重试。第三步轮询任务状态status端点接受taskID查询单个任务不带参数则返回全部任务curl -b cookies.txt http://host:port/api/v2/torrentcreator/status?taskID1响应是任务对象数组每个对象的核心字段statusQueued排队中、Running制作中或Finished已结束progress仅Running时出现表示制作进度timeAdded/timeStarted/timeFinishedUnix 时间戳timeFinished仅在任务结束时出现errorMessage任务失败时出现包含失败原因。判断逻辑status为Finished且没有errorMessage字段说明制作成功可以进入下载步骤有errorMessage说明失败根据消息内容排查常见诱因是sourcePath不可读或torrentFilePath所在目录不可写仍是Queued/Running则继续轮询。第四步下载 .torrent 文件并清理任务任务成功后用torrentFile端点取出文件内容。它返回Content-Type: application/x-bittorrent文件名为taskID.torrentcurl -b cookies.txt -o ubuntu.torrent \ http://host:port/api/v2/torrentcreator/torrentFile?taskID1两个失败模式要注意任务还没做完就调用会返回 409Torrent creation is still unfinished.任务失败时同样返回 409Torrent creation failed.。下载完成后如果不再需要保留这条任务记录可以删除它仅移除 qBittorrent 里的任务条目不影响已生成的 .torrent 文件curl -b cookies.txt -X DELETE http://host:port/api/v2/torrentcreator/deleteTask?taskID1taskID不存在时该端点返回 404。限制与边界整条链路的前提是 qBittorrent 进程本身能读到sourcePath并能在torrentFilePath处写文件API 不接收远程主机上的文件sourcePath只能是服务端的本地路径。认证方式二选一cookie 会话和 API key 会话不能混用API key 会话下auth/*端点一律 403。任务并发数受服务端限制addTask在超限时返回 409需要轮询等待或清理旧任务。生成 .torrent 之后是否做种由startSeeding/torrentFilePath的默认关系决定自动化仅生成文件的流程应保持默认行为提供torrentFilePath且显式不做种若希望生成后立即做种显式传startSeedingtrue。各版本间addTask的参数有差异libtorrent 2 构建用format旧构建用optimizeAlignment/paddedFileSizeLimitstatus的时间字段自 2.16.0 起返回 Unix 时间戳见 WebAPI_Changelog.md对接旧客户端时注意兼容。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考