qBittorrent Web API
配置信息
优先级顺序：
- 项目目录的
.env 文件（默认）
- 项目
CLAUDE.md 文件
- 询问用户提供
# .env 文件格式
QB_URL="http://192.168.31.88:8080"
QB_USER="admin"
QB_PASS="123123"
注意: 执行任何 API 操作前，先检查 .env 文件是否存在并包含配置。如果缺少配置，询问用户。
认证
qBittorrent 使用 cookie-based 认证：
# 配置（从 .env 读取）
source .env 2>/dev/null || true
COOKIE_FILE="/tmp/qb_cookies.txt"
# 登录并保存 cookie
curl -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-H "Referer: $QB_URL" \
-d "username=$QB_USER&password=$QB_PASS" \
"$QB_URL/api/v2/auth/login"
# 登出
curl -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/auth/logout"
重要: 登录请求需要 Referer header。
API 端点速查
认证 /api/v2/auth
种子管理 /api/v2/torrents
文件管理 /api/v2/torrents
速度限制 /api/v2/torrents
优先级 /api/v2/torrents
路径管理 /api/v2/torrents
分类管理 /api/v2/torrents
标签管理 /api/v2/torrents
Tracker 管理 /api/v2/torrents
Web Seeds 管理 /api/v2/torrents
Peers 管理 /api/v2/torrents
其他设置 /api/v2/torrents
传输信息 /api/v2/transfer
应用程序 /api/v2/app
日志 /api/v2/log
同步 /api/v2/sync
RSS /api/v2/rss
搜索 /api/v2/search
单位说明
种子状态
过滤器
torrents/info 支持的过滤器：
all - 全部downloading - 下载中seeding - 做种中completed - 已完成paused - 已暂停active - 活跃inactive - 不活跃resumed - 已恢复stalled - 停滞stalled_uploading - 上传停滞stalled_downloading - 下载停滞errored - 错误
添加种子工作流
重要: 添加种子前必须先查询已有保存路径，然后询问用户保存位置。
步骤 1: 查询已有保存路径
# 获取已有保存路径（按使用频率排序，显示前 10 个）
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info" | \
jq -r '.[].save_path' | sort | uniq -c | sort -rn | head -10
# 获取默认保存路径
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/app/defaultSavePath"
步骤 2: 询问用户保存位置
使用 AskUserQuestion 工具，展示已有路径供用户选择：
问题: 下载文件保存到哪个目录？
选项:
- /m2/ani/番剧 (最常用)
- /m2/movies
- /downloads (默认)
- 其他路径 (用户自定义)
步骤 3: 添加种子
用户选择路径后，执行添加操作：
# Magnet link（用户选择或指定的路径）
curl -c cookies.txt -b cookies.txt \
-d "urls=magnet:?xt=urn:btih:xxxx" \
-d "savepath=$USER_SELECTED_PATH" \
"$QB_URL/api/v2/torrents/add"
# 带分类和标签
curl -c cookies.txt -b cookies.txt \
-d "urls=magnet:?xt=urn:btih:xxxx" \
-d "savepath=$USER_SELECTED_PATH" \
-d "category=movies" \
-d "tags=hd,2024" \
"$QB_URL/api/v2/torrents/add"
# Torrent 文件
curl -c cookies.txt -b cookies.txt \
-F "torrents=@file.torrent" \
-d "savepath=$USER_SELECTED_PATH" \
"$QB_URL/api/v2/torrents/add"
其他操作示例
获取种子列表
# 全部
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info"
# 按状态过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?filter=downloading"
# 按分类过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?category=movies"
# 按标签过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?tag=hd"
# 指定种子
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?hashes=abc123,def456"
控制种子
# 开始
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123" \
"$QB_URL/api/v2/torrents/start"
# 停止
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123" \
"$QB_URL/api/v2/torrents/stop"
### 删除种子
> **重要**: 删除种子时的 `deleteFiles` 参数规则：
>
> | 场景 | deleteFiles | 说明 |
> |------|-------------|------|
> | **默认行为** | `false` | 只删除任务，保留已下载的文件 |
> | 用户明确要求删除文件 | `true` | 用户指定要删除文件时 |
> | 未下载完成的种子 | `true` | progress < 100% 时，删除不完整的文件 |
>
> **安全原则**: 除非用户明确指定或种子未完成，否则默认不删除文件。
```bash
# 删除种子（保留文件）- 默认行为
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
# 删除种子（同时删除文件）- 用户明确要求时
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&deleteFiles=true" \
"$QB_URL/api/v2/torrents/delete"
# 删除多个种子（用 | 分隔）
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123|def456|ghi789&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
# 删除全部种子
curl -c cookies.txt -b cookies.txt \
-d "hashes=all&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
删除前建议检查:
# 检查种子是否完成 (progress=1 表示 100%)
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?hashes=abc123" | jq '.[0].progress'
删除 API 参数
设置限速
# 设置种子下载限速 1 MB/s
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&limit=1048576" \
"$QB_URL/api/v2/torrents/setDownloadLimit"
# 设置种子上传限速 512 KB/s
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&limit=524288" \
"$QB_URL/api/v2/torrents/setUploadLimit"
# 全局限速
curl -c cookies.txt -b cookies.txt \
-d "limit=1048576" \
"$QB_URL/api/v2/transfer/setDownloadLimit"
分类和标签
# 创建分类
curl -c cookies.txt -b cookies.txt \
-d "category=movies&savePath=/downloads/movies" \
"$QB_URL/api/v2/torrents/createCategory"
# 设置分类
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&category=movies" \
"$QB_URL/api/v2/torrents/setCategory"
# 创建标签
curl -c cookies.txt -b cookies.txt \
-d "tags=hd,4k" \
"$QB_URL/api/v2/torrents/createTags"
# 添加标签
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&tags=hd" \
"$QB_URL/api/v2/torrents/addTags"
文件优先级
# 设置文件优先级
# priority: 0=不下载, 1=正常, 6=高, 7=最大
curl -c cookies.txt -b cookies.txt \
-d "hash=abc123&id=0&priority=0" \
"$QB_URL/api/v2/torrents/filePrio"
Tracker 管理
# 获取 trackers
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/trackers?hash=abc123"
# 添加 tracker
curl -c cookies.txt -b cookies.txt \
-d "hash=abc123&urls=udp://tracker.example.com:1337/announce" \
"$QB_URL/api/v2/torrents/addTrackers"
获取传输信息
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/transfer/info"
返回示例：
{
"dl_info_speed": 1048576,
"dl_info_data": 10737418240,
"up_info_speed": 524288,
"up_info_data": 5368709120,
"dl_rate_limit": 0,
"up_rate_limit": 0,
"dht_nodes": 1234,
"connection_status": "connected"
}
完整脚本模板
#!/bin/bash
# 配置 - 从 CLAUDE.md 获取或使用环境变量
QB_URL="${QB_URL:-http://192.168.31.88:8080}"
QB_USER="${QB_USER:-admin}"
QB_PASS="${QB_PASS:-123123}"
COOKIE_FILE="/tmp/qb_cookies.txt"
# 登录
qb_login() {
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-H "Referer: $QB_URL" \
-d "username=$QB_USER&password=$QB_PASS" \
"$QB_URL/api/v2/auth/login"
}
# 登出
qb_logout() {
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/auth/logout"
rm -f "$COOKIE_FILE"
}
# GET 请求
qb_get() {
local endpoint="$1"
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/$endpoint"
}
# POST 请求
qb_post() {
local endpoint="$1"
local data="$2"
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-d "$data" \
"$QB_URL/api/v2/$endpoint"
}
# 使用示例
qb_login
# 获取下载中的种子
qb_get "torrents/info?filter=downloading" | jq '.'
# 添加种子
qb_post "torrents/add" "urls=magnet:?xt=urn:btih:xxxx&savepath=/downloads"
qb_logout
常见问题
官方文档