AntiCAP-WebApi

Appearance

接口总览 ​

AntiCAP-WebApi 后端基于 FastAPI，默认监听 0.0.0.0:6688。接口按认证、管理员和验证码识别三类组织。

基础信息 ​

项目值
默认服务地址http://127.0.0.1:6688
接口格式JSON
认证方式Authorization: Bearer <token>
Swagger 文档/docs
Token 有效期60 天

后续示例统一使用：

bash
BASE_URL="http://127.0.0.1:6688"
TOKEN="your-jwt-token"

请求头 ​

登录接口使用表单格式：

http
Content-Type: application/x-www-form-urlencoded

其他 JSON 接口通常使用：

http
Content-Type: application/json
Authorization: Bearer <token>

扣点规则 ​

识别类接口会经过余额检查：

用户类型扣点
管理员不扣点
普通用户按接口扣点配置扣除

如果接口没有单独配置扣点，默认每次扣 1 点。余额不足时返回 402。

公共接口 ​

用户注册 ​

POST /api/register

使用注册码创建普通用户。注册成功后，用户余额等于注册码的 points。

请求体：

json
{
  "username": "demo",
  "password": "demo-password",
  "registration_code": "registration-code"
}

curl：

bash
curl -X POST "$BASE_URL/api/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "demo",
    "password": "demo-password",
    "registration_code": "registration-code"
  }'

返回：

json
{
  "message": "Registration successful"
}

用户登录 ​

POST /api/login

登录接口使用 OAuth2 表单格式，不接收 JSON。

curl：

bash
curl -X POST "$BASE_URL/api/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=demo&password=demo-password"

返回：

json
{
  "access_token": "jwt-token",
  "token_type": "bearer",
  "role": "user",
  "balance": 1000
}

验证 Token ​

GET /api/tokens/verification

curl：

bash
curl "$BASE_URL/api/tokens/verification" \
  -H "Authorization: Bearer $TOKEN"

返回：

json
{
  "username": "demo",
  "role": "user",
  "balance": 1000
}

管理员接口 ​

管理员接口都需要管理员 JWT。服务启动时会创建默认管理员账号，密码以部署时配置为准：

用户名密码角色
admin部署时设置的密码管理员

生成注册码 ​

POST /api/admin/generate_code

请求体：

json
{
  "points": 1000
}

curl：

bash
curl -X POST "$BASE_URL/api/admin/generate_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"points": 1000}'

返回：

json
{
  "registration_code": "uuid-code",
  "points": 1000
}

获取注册码列表 ​

GET /api/admin/regcodes

查询参数：

参数类型默认值说明
skipnumber0跳过条数
limitnumber100返回条数

curl：

bash
curl "$BASE_URL/api/admin/regcodes?skip=0&limit=100" \
  -H "Authorization: Bearer $TOKEN"

删除注册码 ​

DELETE /api/admin/regcodes/{code_id}

只能删除未使用的注册码。

curl：

bash
curl -X DELETE "$BASE_URL/api/admin/regcodes/1" \
  -H "Authorization: Bearer $TOKEN"

获取用户列表 ​

GET /api/admin/users

curl：

bash
curl "$BASE_URL/api/admin/users?skip=0&limit=100" \
  -H "Authorization: Bearer $TOKEN"

返回：

json
[
  {
    "username": "demo",
    "role": "user",
    "balance": 1000,
    "id": 2
  }
]

修改用户信息 ​

PUT /api/admin/users/{username}

请求体字段均可选：

json
{
  "password": "new-password",
  "balance": 2000
}

curl：

bash
curl -X PUT "$BASE_URL/api/admin/users/demo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new-password",
    "balance": 2000
  }'

获取接口扣点配置 ​

GET /api/admin/costs

curl：

bash
curl "$BASE_URL/api/admin/costs" \
  -H "Authorization: Bearer $TOKEN"

设置接口扣点 ​

POST /api/admin/costs

请求体：

json
{
  "path": "/api/ocr",
  "cost": 2,
  "description": "OCR 识别"
}

curl：

bash
curl -X POST "$BASE_URL/api/admin/costs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/api/ocr",
    "cost": 2,
    "description": "OCR 识别"
  }'

核心识别接口 ​

接口方法文档说明
/api/ocrPOSTOCR 识别识别图片文字
/api/mathPOST计算识别识别数学算式并返回结果
/api/detection/iconPOST图标检测检测图标坐标
/api/detection/textPOST文字检测检测文字坐标
/api/detection/icon/orderPOST图标顺序点击按顺序返回图标点击坐标
/api/detection/text/orderPOST文字顺序点击按顺序返回文字点击坐标
/api/slider/matchPOST缺口滑块缺口滑块坐标识别
/api/slider/comparisonPOST阴影滑块阴影滑块坐标识别
/api/compare/similarityPOST图片相似度返回两图相似度
/api/rotate/single/rotatePOST单图旋转单图旋转验证码识别
/api/rotate/double/rotatePOST双图旋转双图旋转验证码识别

常见错误码 ​

状态码场景
400参数或业务状态错误，例如用户名已注册、注册码无效
401登录失败、Token 无效或 Token 过期
402普通用户余额不足
403非管理员访问管理员接口
404用户、注册码等资源不存在

数据表 ​

后端使用 SQLite，数据库文件为 app.db。

表用途主要字段
users用户账户id、username、hashed_password、role、balance、created_at
registration_codes注册码id、code、is_used、points、created_by、created_at
endpoint_costs接口扣点配置id、path、cost、description

AntiCAP-WebApi