twapi 标准后端 API 文档

完整的用户认证、权限控制和功能管理系统

Base URL: https://tw.jianyuai.top

目录

🎯 系统概述

🔧 核心特性
• 🔐 支持用户名和邮箱双登录方式
• 🎯 8个功能权限开关精确控制
• 💎 VIP会员系统和激活码管理
• 🔄 实时权限状态检查和心跳监控
• 📱 完全适配客户端集成需求

统一响应格式

{ "code": 200, // 状态码：200成功，400客户端错误，401未授权，403权限不足，500服务器错误 "msg": "操作成功", // 提示信息 "data": {}, // 主体数据 "total": 0 // 分页总数（可选） }
重要：所有需要认证的接口都需要在请求头中携带 Authorization: Bearer <token>

🔐 认证系统

GET /captchaImage

功能: 获取图形验证码

描述: 生成验证码图片，支持动态启用/禁用

响应示例

{ "code": 200, "msg": "操作成功", "data": { "captchaEnabled": true, "uuid": "a8d9a6cb-2a14-4892-afc2-266b05f7e87a", "img": "data:image/png;base64,iVBORw0K..." } }

POST /login

功能: 用户登录

描述: 支持用户名和邮箱两种登录方式，自动识别输入类型

请求参数

参数名类型必填说明
usernamestring是用户名或邮箱地址
passwordstring是用户密码
codestring否验证码（可选）
uuidstring否验证码UUID（可选）

请求示例

{ "username": "admin", "password": "123456", "code": "1234", "uuid": "a8d9a6cb-2a14-4892-afc2-266b05f7e87a" }

响应示例

{ "code": 200, "msg": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }

👤 用户信息管理

获取当前用户信息

GET /getInfo

获取当前登录用户的详细信息，包括等级、激活码状态等。

响应示例

{ "code": 200, "msg": "ok", "data": { "userId": 1, "userName": "admin", "level": 4, "levelName": "VIP", "authorizationCode": { "code": "XXXX-XXXX-XXXX", "expirationTime": "2099-12-31T23:59:59", "status": 1 }, "teamCode": [], "isExpire": false } }
字段 类型 说明
isExpire boolean false: 会员/未过期，true: 过期/非会员
level number 用户等级：1=普通用户，4=VIP用户
authorizationCode.status number 激活码状态：0=已过期，1=有效

🔑 权限管理

获取权限状态（核心接口）

GET /license/status

获取用户的权限状态和功能开关，这是权限控制的核心接口。

响应示例

{ "code": 200, "msg": "ok", "data": { "expire": false, "expireAt": "2099-12-31T23:59:59", "plan": "VIP", "features": { "batch_image": true, "img_to_video": true, "flux_js": true, "skip_inference_prompt": true, "vip_skip_watermark": true, "sd_generate": true, "comfyui_generate": true, "video_pipeline_sd": true } } }

心跳检查

GET /license/heartbeat

用于定时校验用户授权状态，建议客户端定期调用。

响应示例

{ "code": 200, "msg": "ok", "data": { "alive": true } }
权限逻辑：
  • expire=false → 客户端应视为 isExpire=false
  • expire=true → 客户端应视为 isExpire=true
  • 管理员用户永不过期，VIP用户根据过期时间动态判断

🎯 功能模块

系统提供8个功能模块，每个模块都有对应的权限控制。

批量生图 VIP

API: POST /api/batch/image

支持批量生成多张图片，提高创作效率。

图生视频 VIP

API: POST /api/img2video

将静态图片转换为动态视频内容。

FLUX_JS模型 VIP

API: POST /api/flux/generate

使用高级FLUX_JS模型进行图像生成。

SD生成 免费

API: POST /api/sd/generate

基础Stable Diffusion图像生成功能。

ComfyUI生成 VIP

API: POST /api/comfyui/generate

使用ComfyUI工作流进行复杂图像生成。

视频处理SD链路 VIP

API: POST /api/video/pipeline

使用SD技术进行视频处理和增强。

VIP去水印 VIP

API: POST /api/watermark/remove

智能去除图片水印，保持画质。

跳过推理提示 VIP

API: GET/POST /api/config/skip-prompt

配置是否跳过AI推理提示步骤。

功能权限表

功能标识 功能名称 免费用户 VIP用户 API路径
batch_image 批量生图 ✗ ✓ /api/batch/image
img_to_video 图生视频 ✗ ✓ /api/img2video
flux_js FLUX_JS模型 ✗ ✓ /api/flux/generate
sd_generate SD生成 ✓ ✓ /api/sd/generate
comfyui_generate ComfyUI生成 ✗ ✓ /api/comfyui/generate
video_pipeline_sd 视频处理SD链路 ✗ ✓ /api/video/pipeline
vip_skip_watermark VIP去水印 ✗ ✓ /api/watermark/remove
skip_inference_prompt 跳过推理提示 ✗ ✓ /api/config/skip-prompt

🎫 激活码系统

绑定激活码

POST /appManage/code

用户使用激活码升级为VIP会员。

请求参数

{ "appId": 1728691835485208578, "code": "XXXX-XXXX", "deviceId": "设备ID（可选）", "bindTime": "绑定时间（可选）" }

响应示例

{ "code": 200, "msg": "激活成功", "data": "ok" }
激活流程：
  1. 用户输入激活码
  2. 系统验证激活码有效性
  3. 更新用户VIP状态和过期时间
  4. 激活码标记为已使用

⚠️ 错误处理

HTTP状态码

状态码 说明 处理建议
200 请求成功 正常处理响应数据
400 请求参数错误 检查请求参数格式和内容
401 未授权/Token无效 重新登录获取新Token
403 权限不足 提示用户升级VIP或联系客服
500 服务器内部错误 稍后重试或联系技术支持

常见错误响应

// Token缺失或无效 { "code": 401, "msg": "Token已过期", "data": null } // 权限不足 { "code": 403, "msg": "需要VIP权限才能使用批量生图功能", "data": null } // 参数错误 { "code": 400, "msg": "提示词不能为空", "data": null }

客户端集成建议

权限检查流程：
  1. 登录后调用 /license/status 获取功能开关状态
  2. 根据 features 对象控制UI功能显示/隐藏
  3. 功能调用时后端自动进行权限验证
  4. 收到403错误时引导用户升级VIP
  5. 定期调用 /license/heartbeat 检查授权状态

🚀 快速开始

以下是一个完整的客户端集成示例：

// 1. 登录获取Token const loginResponse = await fetch('https://tw.jianyuai.top/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'user@example.com', password: 'password123', code: '1234', uuid: 'captcha-uuid' }) }); const { data: { token } } = await loginResponse.json(); // 2. 获取权限状态 const statusResponse = await fetch('https://tw.jianyuai.top/license/status', { headers: { 'Authorization': `Bearer ${token}` } }); const { data: { features } } = await statusResponse.json(); // 3. 根据权限控制功能 if (features.batch_image) { // 显示批量生图功能 enableBatchImageFeature(); } else { // 隐藏功能并显示升级提示 showUpgradePrompt('批量生图需要VIP权限'); } // 4. 调用功能API const generateResponse = await fetch('https://tw.jianyuai.top/api/batch/image', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'beautiful landscape', count: 3 }) }); if (generateResponse.status === 403) { // 权限不足，引导升级VIP showUpgradeDialog(); }

🚀 快速开始

💡 客户端集成建议
建议按照以下步骤进行客户端集成，确保完整替换旧的 bsphp 校验系统。

集成步骤

// 1. 用户登录 const loginResponse = await fetch('https://tw.jianyuai.top/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'your_username', password: 'your_password' }) }); const { data: { token } } = await loginResponse.json(); // 2. 获取用户信息和权限状态 const userInfo = await fetch('https://tw.jianyuai.top/getInfo', { headers: { 'Authorization': `Bearer ${token}` } }); // 3. 检查功能权限 const licenseStatus = await fetch('https://tw.jianyuai.top/license/status', { headers: { 'Authorization': `Bearer ${token}` } }); // 4. 使用功能API（带权限验证） const batchImageResponse = await fetch('https://tw.jianyuai.top/api/batch/image', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ /* 功能参数 */ }) }); if (batchImageResponse.status === 403) { // 权限不足，引导升级VIP showUpgradeDialog(); }
⚠️ 重要提醒
• 所有API调用都需要携带有效的JWT Token
• 功能API会自动进行权限验证
• 建议定期调用心跳接口保持连接
• VIP功能需要有效的激活码

📞 技术支持

如有任何问题，请联系技术支持团队

文档更新时间：2024年12月23日

API版本：v1.0