通用规范

本文档定义平台所有 API 接口的基础规范，所有模块均遵循此约定。

1. Base URL

2. 认证方式

2.1 JWT Token（用户界面操作）

登录成功后获得 access_token，携带于请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• 有效期：2 小时（用户端）/ 8 小时（管理端，IP 绑定）
• 过期后调用 POST /auth/refresh 换取新 Token

2.2 API Key（程序调用）

用于程序直接调用模型接口，格式为 sk- 前缀：

Authorization: Bearer sk-prod-xxxxxxxxxxxxxxxxxxxxxxxx

• 在控制台「API Key 管理」页创建
• 支持按类型（production / test）、IP 白名单、模型白名单和过期时间分类管理

2.3 管理端双因素认证（2FA）

管理员登录需完成两步：

步骤 1：POST /admin/v1/auth/login       → 返回临时 token（5 分钟有效）
步骤 2：POST /admin/v1/auth/2fa/verify  → 验证 TOTP/短信，返回正式 access_token

2.4 密码传输安全（RSA 加密）

所有涉及密码的接口（注册、登录、修改密码、重置密码）均不得明文传输密码。

步骤 1：GET /api/v1/auth/public-key   → 获取 RSA 公钥（有效期 30 分钟）
步骤 2：前端使用公钥加密密码           → Base64(RSA_ENCRYPT(password, public_key))
步骤 3：请求时携带 key_id + 加密密文   → 服务端用私钥解密后再做 bcrypt 处理

详见 02-auth-api.md。

3. 统一响应格式

所有接口均返回以下结构：

{
  "code": 0,
  "message": "success",
  "data": {},
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1704067200
}

3.1 分页响应格式

列表接口统一返回分页结构：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_pages": 5
  }
}

3.2 通用分页查询参数

4. HTTP 状态码

5. 错误码体系

错误响应示例

{
  "code": 1001,
  "message": "Token 已过期，请重新登录",
  "data": null,
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1704067200
}

6. 请求头规范

7. 流式响应（SSE）

模型对话接口支持 Server-Sent Events 流式输出：

POST /api/v1/chat/completions
Content-Type: application/json
Accept: text/event-stream

{"model": "gpt-4o", "messages": [...], "stream": true}

响应格式：

data: {"id":"chatcmpl-001","choices":[{"delta":{"content":"你好"},"index":0}]}

data: {"id":"chatcmpl-001","choices":[{"delta":{"content":"！"},"index":0}]}

data: [DONE]

8. 时间与数据类型约定