Qbittorrent Api

Use when working with qBittorrent Web API - adding torrents, managing downloads, checking status, or any qBittorrent automation task. Includes curl examples and common patterns.

qBittorrent Web API

配置信息

优先级顺序：

1. 项目目录的 .env 文件（默认）
2. 项目 CLAUDE.md 文件
3. 询问用户提供

bash

# .env 文件格式
QB_URL="http://192.168.31.88:8080"
QB_USER="admin"
QB_PASS="123123"

注意: 执行任何 API 操作前，先检查 .env 文件是否存在并包含配置。如果缺少配置，询问用户。

认证

qBittorrent 使用 cookie-based 认证：

bash

# 配置（从 .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

操作	端点	方法	参数
登录	/login	POST	username, password
登出	/logout	POST	-

种子管理 /api/v2/torrents

操作	端点	方法	参数
种子列表	/info	GET	filter, hashes, category, tag
种子数量	/count	GET	filter
种子详情	/properties	GET	hash
添加种子	/add	POST	urls, savepath, category, tags
删除种子	/delete	POST	hashes, deleteFiles
开始	/start	POST	hashes
停止	/stop	POST	hashes
重新检查	/recheck	POST	hashes
重新宣告	/reannounce	POST	hashes
重命名	/rename	POST	hash, name
设置注释	/setComment	POST	hashes, comment

文件管理 /api/v2/torrents

操作	端点	方法	参数
文件列表	/files	GET	hash
文件优先级	/filePrio	POST	hash, id, priority
重命名文件	/renameFile	POST	hash, oldPath, newPath
重命名文件夹	/renameFolder	POST	hash, oldPath, newPath

速度限制 /api/v2/torrents

操作	端点	方法	参数
获取下载限速	/downloadLimit	GET	hashes
获取上传限速	/uploadLimit	GET	hashes
设置下载限速	/setDownloadLimit	POST	hashes, limit
设置上传限速	/setUploadLimit	POST	hashes, limit
设置分享限制	/setShareLimits	POST	hashes, ratioLimit, seedingTimeLimit

优先级 /api/v2/torrents

操作	端点	方法	参数
提高优先级	/increasePrio	POST	hashes
降低优先级	/decreasePrio	POST	hashes
最高优先级	/topPrio	POST	hashes
最低优先级	/bottomPrio	POST	hashes

路径管理 /api/v2/torrents

操作	端点	方法	参数
设置保存路径	/setLocation	POST	hashes, location
设置保存目录	/setSavePath	POST	hashes, path
设置下载目录	/setDownloadPath	POST	hashes, path

分类管理 /api/v2/torrents

操作	端点	方法	参数
获取分类	/categories	GET	-
创建分类	/createCategory	POST	category, savePath
编辑分类	/editCategory	POST	category, savePath
删除分类	/removeCategories	POST	categories
设置分类	/setCategory	POST	hashes, category

标签管理 /api/v2/torrents

操作	端点	方法	参数
获取标签	/tags	GET	-
创建标签	/createTags	POST	tags
删除标签	/deleteTags	POST	tags
添加标签	/addTags	POST	hashes, tags
设置标签	/setTags	POST	hashes, tags
移除标签	/removeTags	POST	hashes, tags

Tracker 管理 /api/v2/torrents

操作	端点	方法	参数
获取 Trackers	/trackers	GET	hash
添加 Trackers	/addTrackers	POST	hash, urls
编辑 Tracker	/editTracker	POST	hash, origUrl, newUrl
删除 Trackers	/removeTrackers	POST	hash, urls

Web Seeds 管理 /api/v2/torrents

操作	端点	方法	参数
获取 Web Seeds	/webseeds	GET	hash
添加 Web Seeds	/addWebSeeds	POST	hash, urls
编辑 Web Seed	/editWebSeed	POST	hash, origUrl, newUrl
删除 Web Seeds	/removeWebSeeds	POST	hash, urls

Peers 管理 /api/v2/torrents

操作	端点	方法	参数
添加 Peers	/addPeers	POST	hashes, peers

其他设置 /api/v2/torrents

操作	端点	方法	参数
自动管理	/setAutoManagement	POST	hashes, enable
超级做种	/setSuperSeeding	POST	hashes, value
强制开始	/setForceStart	POST	hashes, value
顺序下载	/toggleSequentialDownload	POST	hashes
首尾块优先	/toggleFirstLastPiecePrio	POST	hashes

传输信息 /api/v2/transfer

操作	端点	方法	参数
传输信息	/info	GET	-
下载限速	/downloadLimit	GET	-
上传限速	/uploadLimit	GET	-
设置下载限速	/setDownloadLimit	POST	limit
设置上传限速	/setUploadLimit	POST	limit
切换备用限速	/toggleSpeedLimitsMode	POST	-

应用程序 /api/v2/app

操作	端点	方法	参数
版本	/version	GET	-
API 版本	/webapiVersion	GET	-
构建信息	/buildInfo	GET	-
关闭	/shutdown	POST	-
获取设置	/preferences	GET	-
设置偏好	/setPreferences	POST	json
默认保存路径	/defaultSavePath	GET	-

日志 /api/v2/log

操作	端点	方法	参数
日志	/main	GET	normal, info, warning, critical
Peer 日志	/peers	GET	last_known_id

同步 /api/v2/sync

操作	端点	方法	参数
主数据	/maindata	GET	rid
种子 Peers	/torrentPeers	GET	hash, rid

RSS /api/v2/rss

操作	端点	方法	参数
添加文件夹	/addFolder	POST	path
添加订阅	/addFeed	POST	url, path
移除	/removeItem	POST	path
移动	/moveItem	POST	itemPath, destPath
获取文章	/items	GET	withData
标记已读	/markAsRead	POST	itemPath, articleId
刷新	/refreshItem	POST	itemPath
设置自动下载规则	/setRule	POST	ruleName, ruleDef
删除规则	/removeRule	POST	ruleName
获取规则	/rules	GET	-
匹配规则	/matchingArticles	GET	ruleName

搜索 /api/v2/search

操作	端点	方法	参数
启动搜索	/start	POST	pattern, plugins, category
停止搜索	/stop	POST	id
搜索状态	/status	GET	id
搜索结果	/results	GET	id, limit, offset
删除搜索	/delete	POST	id
获取插件	/plugins	GET	-
安装插件	/installPlugin	POST	sources
卸载插件	/uninstallPlugin	POST	names
启用插件	/enablePlugin	POST	names, enable
更新插件	/updatePlugins	POST	-

---

单位说明

参数	单位	换算
limit (限速)	bytes/second	1 MB/s = 1048576
size	bytes	-
progress	0-1 浮点数	0.5 = 50%
priority	整数	0=不下载, 1=正常, 6=高, 7=最大

---

种子状态

状态	含义
error	错误
missingFiles	文件丢失
uploading	做种中
pausedUP	暂停做种
queuedUP	排队做种
stalledUP	做种停滞
checkingUP	检查中
forcedUP	强制做种
allocating	分配空间
downloading	下载中
metaDL	下载元数据
pausedDL	暂停下载
queuedDL	排队下载
stalledDL	下载停滞
checkingDL	检查中
forcedDL	强制下载
checkingResumeData	检查恢复数据
moving	移动中
unknown	未知

---

过滤器

torrents/info 支持的过滤器：

• all - 全部
• downloading - 下载中
• seeding - 做种中
• completed - 已完成
• paused - 已暂停
• active - 活跃
• inactive - 不活跃
• resumed - 已恢复
• stalled - 停滞
• stalled_uploading - 上传停滞
• stalled_downloading - 下载停滞
• errored - 错误

---

添加种子工作流

重要: 添加种子前必须先查询已有保存路径，然后询问用户保存位置。

步骤 1: 查询已有保存路径

bash

# 获取已有保存路径（按使用频率排序，显示前 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 工具，展示已有路径供用户选择：

text

问题: 下载文件保存到哪个目录？

选项:
- /m2/ani/番剧 (最常用)
- /m2/movies
- /downloads (默认)
- 其他路径 (用户自定义)

步骤 3: 添加种子

用户选择路径后，执行添加操作：

bash

# 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"

---

其他操作示例

获取种子列表

bash

# 全部
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"

控制种子

bash

# 开始
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"

删除前建议检查:

bash

# 检查种子是否完成 (progress=1 表示 100%)
curl -c cookies.txt -b cookies.txt \
  "$QB_URL/api/v2/torrents/info?hashes=abc123" | jq '.[0].progress'

删除 API 参数

参数	类型	必填	说明
hashes	string	✅	种子 hash，多个用 | 分隔，all 删除全部
deleteFiles	bool	❌	是否删除文件，默认 false

设置限速

bash

# 设置种子下载限速 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"

分类和标签

bash

# 创建分类
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"

文件优先级

bash

# 设置文件优先级
# 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 管理

bash

# 获取 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"

获取传输信息

bash

curl -c cookies.txt -b cookies.txt \
  "$QB_URL/api/v2/transfer/info"

返回示例：

json

{
  "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"
}

---

完整脚本模板

bash

#!/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

---

常见问题

问题	解决方案
登录失败	检查 Referer header
Cookie 不生效	确保同时使用 -c 和 -b
限速不生效	单位是 bytes/s，不是 KB/s
找不到种子	用 torrents/info 查询 hash
中文乱码	确保 URL 编码
403 Forbidden	检查白名单设置或 CSRF 保护

---

官方文档

• OpenAPI: https://www.qbittorrent.org/openapi-demo/
• Wiki: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)
• API Changelog: https://github.com/qbittorrent/qBittorrent/blob/master/WebAPI_Changelog.md