qBittorrent Web API

配置信息

优先级顺序：

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

# .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% 时，删除不完整的文件 |
>
> **安全原则**: 除非用户明确指定或种子未完成，否则默认不删除文件。

删除种子（保留文件）- 默认行为

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 参数

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

### 设置限速

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

---

## 常见问题

| 问题 | 解决方案 |
|------|----------|
| 登录失败 | 检查 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