REST API 总览

所有 REST API 的基础路径为 /api/v1。

请求/响应规范

• Content-Type: application/json，UTF-8 编码
• 字段命名: snake_case（如 created_at、user_id）
• 日期时间: ISO 8601 格式（如 2026-03-24T10:30:00Z）
• ID 格式: UUID v4（如 550e8400-e29b-41d4-a716-446655440000）

认证

除少数公开端点外，所有请求须携带 JWT Token：

Authorization: Bearer <token>

详见 认证与授权。

通用查询参数

大部分列表端点支持以下标准参数：

参数	类型	默认值	说明
offset	int	0	跳过前 N 条记录
limit	int	50	返回数量（最大 100）
desc	bool	true	是否降序排列
order	string	created_at	排序字段：created_at 或 updated_at
scope	string	own	资源作用域：own、public、all

详见 分页与排序、权限与作用域。

错误响应格式

标准错误

{
  "detail": "错误描述信息"
}

验证错误（422）

{
  "detail": [
    {
      "loc": ["body", "phone"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

端点总览

公开端点（无需认证）

方法	路径	说明
GET	/api/v1/health	健康检查
GET	/api/v1/auth/verification-code	获取验证码
POST	/api/v1/auth/token	登录/注册
POST	/api/v1/payments/wechat/callback	微信支付回调

用户资源端点

资源	前缀	说明	详情
用户	/users	用户信息、权限管理	用户管理
AI 角色	/characters	AI 角色配置	AI 角色
用户角色配置	/user-character-configs	用户对角色的个性化配置	AI 角色
对话	/conversations	对话管理	对话管理
项目	/projects	项目及画布	项目与画布
画布	/canvas	画布节点/边操作	项目与画布
节点组	/node-groups	共享节点组	项目与画布
文件	/files	用户文件上传	文件管理
收藏	/favorites	收藏管理	—
技能	/skills	用户创建的技能	技能系统

生成器端点

资源	前缀	说明	详情
生成器列表	/generators	可用生成器查询	内容生成
生成任务	/generations	提交生成任务	内容生成
参数 Schema	/generations/schemas	生成器参数定义	内容生成

计费端点

资源	前缀	说明	详情
充值交易	/payments	充值订单管理	计费与支付
套餐	/bundles	充值套餐查询	计费与支付
交易流水	/transaction-logs	消费/充值流水	计费与支付
邀请码	/invite-codes	邀请奖励	计费与支付

配置端点（只读）

资源	前缀	说明
LLM 配置	/llms/*	可用大语言模型列表
工具列表	/tools/functions	可用工具查询
工具集	/tool-sets	工具集管理

管理员端点

资源	前缀	说明	详情
服务器配置	/server-config	运行时配置	管理员接口
短信服务	/verification-code-providers	短信通道管理	管理员接口
微信 API	/wechat-api	微信支付配置	管理员接口

WebSocket 端点

端点	用途
ws://.../conversations/{id}/ws?token=xxx	对话实时通信
ws://.../projects/{id}/ws?token=xxx	项目协作（画布 + 对话）
ws://.../canvas/{id}/ws?token=xxx	画布编辑

详见 WebSocket 协议。