API 参考

TG2AI 提供 RESTful API，便于集成与自动化调用。

---

基础信息

项目	说明
Base URL	https://api.tg2ai.com
API 版本	v1
数据格式	JSON

获取访问凭证

调用需要认证的接口前，请先在控制台「系统设置 → API Key 管理」中生成一个 API Key，或使用登录后获取的 JWT Token。

---

认证

部分接口需要认证。系统支持：

• JWT Token：登录后获取，在请求头中携带 Authorization: Bearer <token>
• API Key：部分模块支持 API Key 认证

# 使用 JWT 调用需认证的接口
curl -H "Authorization: Bearer <your_jwt_token>" \
  https://api.tg2ai.com/api/v1/accounts

---

通用响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应

{
  "detail": "错误描述信息",
  "status_code": 400
}

分页响应

{
  "items": [...],
  "total": 100,
  "page": 1,
  "page_size": 20
}

---

核心接口分类

健康检查

方法	路径	说明
GET	/health	服务健康检查

示例：

curl https://api.tg2ai.com/health

响应：

{
  "status": "ok",
  "version": "3.0.0"
}

---

账号管理

方法	路径	说明
GET	/api/v1/accounts	获取账号列表
POST	/api/v1/accounts	添加账号
PUT	/api/v1/accounts/{id}	更新账号
DELETE	/api/v1/accounts/{id}	删除账号
GET	/api/v1/accounts/statistics	获取账号统计
POST	/api/v1/accounts/check-spam	批量检测封禁

---

文件夹 / 分组

方法	路径	说明
GET	/api/v1/folders	获取文件夹列表
GET	/api/v1/folders/stats	获取文件夹统计
POST	/api/v1/folders	创建文件夹
PUT	/api/v1/folders/{id}	更新文件夹
DELETE	/api/v1/folders/{id}	删除文件夹

---

全局设置

方法	路径	说明
GET	/api/v1/settings/global	获取全局设置
PUT	/api/v1/settings/global	更新全局设置
POST	/api/v1/settings/global/reset	重置为默认值
GET	/api/v1/settings/themes	获取终端主题列表
GET	/api/v1/settings/languages	获取语言列表

---

模块控制

模块接口统一格式：/api/v1/modules/{module-slug}/{action}

操作	方法	路径示例	说明
启动	POST	/api/v1/modules/{slug}/start	启动模块任务
状态	GET	/api/v1/modules/{slug}/status/{task_id}	查询任务状态
停止	POST	/api/v1/modules/{slug}/stop/{task_id}	停止任务
任务列表	GET	/api/v1/modules/{slug}/tasks	获取任务列表

常用模块 slug 示例：

模块	slug
私信群发	direct-spammer
直接群发	spam-sender
群组群发	group-spammer
普通邀请	inviter
用户解析	user-parser
群组解析	group-parser
频道解析	channel-parser

---

配置管理

方法	路径	说明
GET	/api/configs	获取配置列表
GET	/api/v1/configs	获取配置列表（v1）
GET	/api/v1/configs/module/{module_name}	获取模块配置
POST	/api/v1/configs/save	保存配置
DELETE	/api/configs/{id}	删除配置

---

错误码与处理

HTTP 状态码	说明
200	成功
201	创建成功
400	请求参数错误
401	未认证或 Token 无效
403	无权限
404	资源不存在
422	校验失败（如 Pydantic 校验）
500	服务器内部错误

常见错误处理

// 示例：处理 API 错误
try {
  const res = await fetch('https://api.tg2ai.com/api/v1/accounts');
  if (!res.ok) {
    const err = await res.json();
    console.error('API Error:', err.detail || err.message);
    // 401: 重新登录获取 Token
    // 403: 检查权限
    // 500: 联系管理员
  }
} catch (e) {
  console.error('Network error:', e);
}

---

常用模块 API 前缀

所有模块接口均需登录认证（JWT 或 API Key），完整的模块清单与操作步骤见 功能模块总览。