NXAI 后端 API 接口文档

概述

本文档涵盖 NXAI 项目后端自有的 REST API 接口（非 AI 模型中转代理接口）。所有接口均以 /api 为前缀，通过 Nginx 反向代理对外暴露为 /test/api/*。

基础信息

项目	说明
基础路径（内网）	`http://localhost:8081/api`
基础路径（外网）	`https://your-domain/test/api`
数据格式	`application/json`
认证方式	请求头 `token`（JWT）

通用响应格式

json

{
  "statusCode": 2200,
  "code": 200,
  "message": "操作成功",
  "type": 0,
  "data": {}
}

通用状态码

statusCode	说明
2200	成功
4001	未登录或登录态已失效
4002	无权限访问
4003	参数错误
4005	用户已被禁用
4012	操作频繁
4015	令牌已过期
4204	无数据
4401	删除时找不到记录
4501	已有重复数据

一、AI 网关核心

1.1 获取模型列表

POST /api/ai/models

请求参数

参数	类型	必填	说明
apiKey	string	否	API 密钥
baseUrl	string	否	基础 URL
forceRefresh	boolean	否	是否强制刷新缓存

请求示例

json

{
  "apiKey": "sk-xxx",
  "baseUrl": "https://api.openai.com",
  "forceRefresh": false
}

响应示例

json

{
  "statusCode": 2200,
  "data": {
    "models": [...],
    "total": 100
  }
}

1.2 获取模型列表缓存快照

GET /api/ai/models/cache

无需请求参数，返回当前缓存的模型列表快照。

1.3 获取自动优选模型列表

GET /api/ai/auto/preferred-models?capability={capability}

查询参数

参数	类型	必填	说明
capability	string	否	按能力过滤（如：`text`, `image`, `video`）

1.4 设置初始分组和密钥

POST /api/ai/setInitGroupAndKey

请求参数

参数	类型	必填	说明
username	string	是	用户名
groups	array	是	分组列表

1.5 获取初始分组和密钥

GET /api/ai/initGroupAndKey?sessionId={sessionId}

查询参数

参数	类型	必填	说明
sessionId	string	是	会话 ID

1.6 聊天补全（非流式）

POST /api/ai/chat/completions

请求参数

参数	类型	必填	说明
apiKey	string	否	API 密钥
baseUrl	string	否	基础 URL
provider	string	否	提供商（如：openai, anthropic, google）
model	string	是	模型名称
messages	array[object]	是	消息列表
└─ role	string	是	角色：`user`, `assistant`, `system`
└─ content	string	是	消息内容
temperature	number	否	采样温度（0-2）
maxTokens	integer	否	最大生成 token 数
topP	number	否	核采样参数
n	integer	否	生成的补全数
stream	boolean	否	是否流式（设为 false 或省略）
stop	string	否	停止序列
sessionId	string	否	会话 ID
groupName	string	否	分组名称
temporaryUserId	string	否	临时用户 ID
clientStreamId	string	否	流式恢复 ID（前端生成）
mcpWebSearch	boolean	否	是否启用 MCP 联网搜索
reasoningEffort	string	否	推理强度：`low` / `medium` / `high`
providerOptions	object	否	提供商特定参数（如 thinking 配置）

请求示例

json

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "stream": false
}

请求头

头	说明
token	可选，登录后的 JWT token

1.7 专业版聊天补全（非流式）

POST /api/ai/pro/chat/completions

参数同 1.6，使用专业版通道。

1.8 聊天补全（流式 SSE）

POST /api/ai/chat/completions/stream

请求参数 同 1.6，但 stream 应设为 true。

响应格式：text/event-stream（SSE）

data: {"choices":[{"delta":{"content":"Hello"},"index":0}]}
data: {"choices":[{"delta":{"content":"! How"},"index":0}]}
data: {"choices":[{"delta":{"content":" can I help?"},"index":0}]}
data: [DONE]

1.9 专业版聊天补全（流式 SSE）

POST /api/ai/pro/chat/completions/stream

参数同 1.6，使用专业版通道进行流式响应。

1.10 流式断流恢复

GET /api/ai/chat/stream-recovery/{clientStreamId}

路径参数

参数	类型	说明
clientStreamId	string	前端生成的流式恢复 ID

用于刷新页面后拉取已累积的流式文本（内存态，进程重启后不可用）。

二、认证与用户

2.1 获取公开配置

GET /api/auth/public-config

无需登录。返回是否开放注册、主站注册 URL。

响应示例

json

{
  "statusCode": 2200,
  "data": {
    "publicRegisterEnabled": true,
    "upstreamRegisterUrl": "https://example.com/register"
  }
}

2.2 用户注册

POST /api/auth/register

请求参数

参数	类型	必填	说明
email	string	是	邮箱
username	string	是	用户名
password	string	是	密码

请求示例

json

{
  "email": "user@example.com",
  "username": "testuser",
  "password": "password123"
}

2.3 用户登录

POST /api/auth/login

请求参数

参数	类型	必填	说明
email	string	是	邮箱
password	string	是	密码

响应示例

json

{
  "statusCode": 2200,
  "data": {
    "token": "jwt_token_string",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "user@example.com"
    }
  }
}

2.4 AI 网关 SSO 单点登录

POST /api/auth/sso/gateway

用 AI 网关签发的短期 JWT 兑换本站 session。

2.5 AI（new-api）注册成功回调

POST /api/auth/internal/provision-from-ai

请求头

头	说明
X-Nxai-Provision-Secret	预配密钥，需与 `NXAI_PROVISION_SECRET` 配置一致

2.6 获取当前用户信息

GET /api/auth/me

请求头

头	必填	说明
token	是	JWT token

2.7 更新头像（JSON 方式）

PATCH /api/auth/me/avatar
Content-Type: application/json

请求参数

参数	类型	必填	说明
avatarBase64	string	是	Base64 编码的图片数据

2.8 更新头像（Multipart 上传）

PUT /api/auth/me/avatar
Content-Type: multipart/form-data

请求参数

参数	类型	必填	说明
file	file	是	头像图片文件，字段名为 `file`

2.9 游客心跳

POST /api/auth/guest/heartbeat

用于游客模式的心跳保活。

三、聊天会话

所有接口需登录（请求头携带 token）。

3.1 列出会话

GET /api/chat/sessions

3.2 创建会话

POST /api/chat/sessions

请求参数

参数	类型	必填	说明
title	string	否	会话标题
model	string	否	关联的模型
systemPrompt	string	否	系统提示词

3.3 获取会话详情

GET /api/chat/sessions/{sessionId}

3.4 保存会话

PUT /api/chat/sessions/{sessionId}

3.5 置顶/取消置顶会话

PATCH /api/chat/sessions/{sessionId}/pin

请求参数

参数	类型	必填	说明
pinned	boolean	否	是否置顶

3.6 重命名会话

PATCH /api/chat/sessions/{sessionId}/title

请求参数

参数	类型	必填	说明
title	string	是	新标题

3.7 删除会话

DELETE /api/chat/sessions/{sessionId}

四、图片生成

4.1 图片生成（非流式）

POST /api/image/generations

请求参数

参数	类型	必填	说明
apiKey	string	否	API 密钥
baseUrl	string	否	基础 URL
model	string	是	模型名称
prompt	string	是	提示词
negativePrompt	string	否	负面提示词
size	string	否	图片尺寸（如 `1024x1024`）
aspectRatio	string	否	宽高比（如 `1:1`）
imageSize	string	否	图片大小规格
quality	string	否	质量（如 `standard`, `hd`）
style	string	否	风格（如 `vivid`, `natural`）
n	integer	否	生成图片数量
responseFormat	string	否	响应格式（如 `url`, `b64_json`）
background	string	否	背景
outputFormat	string	否	输出格式
outputCompression	integer	否	输出压缩率
strength	number	否	图生图强度
seed	integer	否	随机种子
steps	integer	否	采样步数
stream	boolean	否	是否流式
watermark	boolean	否	是否加水印
inputImages	array[object]	否	输入图片列表（图生图）
sessionId	string	否	会话 ID
groupName	string	否	分组名称
temporaryUserId	string	否	临时用户 ID
extraOptions	object	否	额外选项
thinking	string	否	思考模式（如 `high`, `off`）
geminiGoogleSearch	boolean	否	Gemini 是否启用 Google 搜索
clientStreamId	string	否	流式恢复 ID
taskType	string	否	任务类型

4.2 图片生成（流式 SSE）

POST /api/image/generations/stream

参数同 4.1，返回 SSE 流式响应。

4.3 图片流式断流恢复

GET /api/image/generations/stream-recovery/{clientStreamId}

五、图片记录

所有接口需登录（请求头携带 token）。

5.1 列出图片记录

GET /api/image/records

5.2 获取单条图片记录

GET /api/image/records/{recordId}

5.3 创建图片记录

POST /api/image/records

5.4 更新图片记录

PUT /api/image/records/{recordId}

六、视频生成

6.1 视频生成

POST /api/video/generations

请求参数 类似图片生成，包含 apiKey, baseUrl, model, prompt 等。

6.2 查询视频任务状态

POST /api/video/generations/{taskId}

6.3 创建视频任务（异步 Job）

POST /api/video/jobs

6.4 查询视频 Job 状态

POST /api/video/jobs/{jobId}

6.5 视频 Job 进度流式推送

GET /api/video/jobs/{jobId}/stream

返回 SSE 流式响应，实时推送视频生成进度。

七、视频记录

所有接口需登录（请求头携带 token）。

7.1 列出视频记录

GET /api/video/records

7.2 获取单条视频记录

GET /api/video/records/{recordId}

7.3 创建视频记录

POST /api/video/records

7.4 更新视频记录

PUT /api/video/records/{recordId}

八、作品管理

8.1 列出作品

GET /api/works?scene={scene}&limit={limit}&offset={offset}&temporaryUserId={temporaryUserId}

查询参数

参数	类型	必填	说明
scene	string	否	场景过滤
limit	integer	否	每页数量（默认 30）
offset	integer	否	偏移量（默认 0）
temporaryUserId	string	否	临时用户 ID

认证：支持 Header token 或 URL 查询参数 token。

8.2 删除作品

DELETE /api/works/{workId}?temporaryUserId={temporaryUserId}

响应说明

状态码	说明
2200	删除成功
4401	未找到该记录
4002	无权限
4001	未认证

8.3 创建代码作品

POST /api/works/code

请求参数

参数	类型	必填	说明
title	string	是	作品标题
description	string	否	作品描述
assetIds	array[integer]	是	关联的资产 ID 列表
temporaryUserId	string	否	临时用户 ID

8.4 更新作品标题

PUT /api/works/{workId}/title?temporaryUserId={temporaryUserId}

请求参数

参数	类型	必填	说明
title	string	是	新标题

8.5 获取作品资产内容

GET /api/works/assets/{assetId}/content?temporaryUserId={temporaryUserId}

返回资产文件的二进制内容（支持通过 token 查询参数认证）。适用于 img、video 等标签的直接引用。

九、文件上传

9.1 上传文件

POST /api/files/upload
Content-Type: multipart/form-data

请求参数

参数	类型	必填	说明
file	file	是	上传的文件，字段名为 `file`

响应示例

json

{
  "statusCode": 2200,
  "data": {
    "previewUrl": "/api/assets/local/code/2025/06/02/abc123.html",
    "assetId": 42
  }
}

9.2 上传代码文本

POST /api/files/upload-text
Content-Type: application/json

请求参数

参数	类型	必填	说明
codeContent	string	是	代码文本内容
language	string	否	代码语言（如 `javascript`, `python`, `html`），默认 `txt`
filename	string	否	自定义文件名

响应示例

json

{
  "statusCode": 2200,
  "data": {
    "previewUrl": "/api/assets/local/code/2025/06/02/def456.js",
    "assetId": 43,
    "filename": "script.js"
  }
}

支持的语言：html, javascript, typescript, vue, css, scss, markdown, json, xml, python, java, go, rust, cpp, c, php, ruby, shell, yaml, sql 等。

十、本地资产访问

10.1 通过 assetId 预览资产

GET /api/assets/preview/{assetId}

返回资产文件的二进制内容，缓存期 365 天。

10.2 通过编码 ID 分享资产

GET /api/assets/share/{encodedId}

encodedId 为 Base64 URL 编码的资产 ID（格式：a_{id}）。

10.3 访问本地资产文件

GET /api/assets/local/{filePath}

认证方式：支持 Header token 或 URL 查询参数 token、temporaryUserId。

权限说明

头像文件（avatars/ 目录）：仅本人可访问
代码资产（code/ 目录）：关联作品有权限即可访问
其他资产：需校验作品归属

十一、模型能力与协议

11.1 解析模型图片能力矩阵

GET /api/ai/model-capability/image/resolve?modelId={modelId}

参数	类型	必填	说明
modelId	string	是	模型 ID

11.2 解析模型协议详情

GET /api/ai/model-protocol/resolve?modelId={modelId}&scene={scene}

参数	类型	必填	说明
modelId	string	是	模型 ID
scene	string	否	场景（`chat` / `image`），默认 `chat`

11.3 列出协议配置

GET /api/ai/model-protocol/list?scene={scene}

参数	类型	必填	说明
scene	string	否	场景过滤

十二、模型测试

12.1 列出可用测试用例

GET /api/model-test/cases?target={target}&modelId={modelId}

参数	类型	必填	说明
target	string	是	测试目标
modelId	string	否	模型 ID

12.2 创建测试运行

POST /api/model-test/runs

12.3 获取测试运行结果

GET /api/model-test/runs/{runId}

十三、技能

13.1 列出可用技能

GET /api/ai/skills?scene={scene}

参数	类型	必填	说明
scene	string	否	场景（默认 `chat`）

十四、助手（Assistants）

14.1 列出公开助手

GET /api/assistants/public

无需登录。

14.2 列出个人助手

GET /api/assistants/personal

需登录（请求头携带 token）。

14.3 列出社区助手

GET /api/assistants/list-community

无需登录。

14.4 获取助手详情

GET /api/assistants/{id}

需登录。

14.5 创建助手

POST /api/assistants

需登录。

参数	类型	必填	说明
name	string	是	助手名称
description	string	否	助手描述
systemPrompt	string	否	系统提示词
model	string	否	关联模型
...			其他助手属性

14.6 更新助手

PUT /api/assistants

需登录。

参数	类型	必填	说明
id	integer	是	助手 ID
name	string	否	助手名称
description	string	否	助手描述
...			其他需要更新的字段

14.7 删除助手

DELETE /api/assistants/{id}

需登录。

14.8 分享/取消分享助手

POST /api/assistants/share

需登录。

参数	类型	必填	说明
id	integer	是	助手 ID
share	boolean	是	是否分享

14.9 获取分享的助手

GET /api/assistants/shared/{shareCode}

无需登录，通过分享码获取助手信息。

14.10 导入分享的助手

POST /api/assistants/import/{shareCode}

需登录，导入他人分享的助手到自己的助手列表中。

十五、Agent 智能体

15.1 提示词润色

POST /api/agents/prompt-polish

需登录（请求头携带 token）。

参数	类型	必填	说明
prompt	string	是	原始提示词
targetLanguage	string	否	目标语言

十六、Vibe Coding

16.1 创建 Vibe Coding 会话

POST /api/vibe-coding/sessions

参数	类型	必填	说明
giteeToken	string	否	Gitee 访问令牌
giteeOwner	string	否	Gitee 仓库所有者
repoName	string	否	仓库名称
isPrivate	boolean	否	是否私有仓库
projectDescription	string	否	项目描述
techStack	string	否	技术栈
additionalRequirements	string	否	额外需求

16.2 连接 Vibe Coding 流

GET /api/vibe-coding/sessions/{sessionId}/stream

返回 SSE 流式响应。

16.3 响应 Vibe Coding 提示

POST /api/vibe-coding/sessions/{sessionId}/respond

参数	类型	必填	说明
response	string	是	用户的响应内容

16.4 中止 Vibe Coding 会话

POST /api/vibe-coding/sessions/{sessionId}/abort

16.5 获取 Vibe Coding 会话状态

GET /api/vibe-coding/sessions/{sessionId}/status

十七、API 访问令牌

所有接口需登录（请求头携带 token）。

17.1 列出令牌

GET /api/access/tokens

17.2 幂等创建默认令牌

POST /api/access/tokens/ensure-default

进入令牌页面时调用，如果无系统默认令牌则自动创建。

17.3 创建新令牌

POST /api/access/tokens

参数	类型	必填	说明
name	string	否	令牌名称
modelLimits	array	否	模型限制
groupLimits	array	否	分组限制

17.4 更新令牌状态

PATCH /api/access/tokens/{tokenId}/status

参数	类型	必填	说明
active	boolean	否	是否启用

17.5 删除令牌

DELETE /api/access/tokens/{tokenId}

17.6 获取临时令牌

GET /api/access/tokens/temporary?temporaryUserId={temporaryUserId}

17.7 创建/更新临时令牌

POST /api/access/tokens/temporary

参数	类型	必填	说明
temporaryUserId	string	否	临时用户 ID
apiKey	string	否	API 密钥

十八、API 访问日志

所有接口需登录（请求头携带 token）。

18.1 查询使用日志

GET /api/access/logs?type={type}&page={page}&pageSize={pageSize}&startTimestamp={start}&endTimestamp={end}&tokenName={name}&modelName={model}&group={group}&requestId={requestId}

查询参数

参数	类型	必填	说明
type	string	否	日志类型（默认 `2`）
page	integer	否	页码
pageSize	integer	否	每页数量
startTimestamp	integer	否	起始时间戳
endTimestamp	integer	否	结束时间戳
tokenName	string	否	令牌名称过滤
modelName	string	否	模型名称过滤
group	string	否	分组过滤
requestId	string	否	请求 ID 过滤

18.2 获取使用统计

GET /api/access/logs/stat?type={type}&startTimestamp={start}&endTimestamp={end}&tokenName={name}&modelName={model}&group={group}

统计参数同 18.1（不含分页参数）。

基础聊天(ChatCompletions格式)

会话聊天(Responses格式)

OpenAI聊天格式

Gemini原生格式

NXAI 后端 API 接口文档 ​

概述 ​

基础信息 ​

通用响应格式 ​

通用状态码 ​

一、AI 网关核心 ​

1.1 获取模型列表 ​

1.2 获取模型列表缓存快照 ​

1.3 获取自动优选模型列表 ​

1.4 设置初始分组和密钥 ​

1.5 获取初始分组和密钥 ​

1.6 聊天补全（非流式） ​

1.7 专业版聊天补全（非流式） ​

1.8 聊天补全（流式 SSE） ​

1.9 专业版聊天补全（流式 SSE） ​

1.10 流式断流恢复 ​

二、认证与用户 ​

2.1 获取公开配置 ​

2.2 用户注册 ​

2.3 用户登录 ​

2.4 AI 网关 SSO 单点登录 ​

2.5 AI（new-api）注册成功回调 ​

2.6 获取当前用户信息 ​

2.7 更新头像（JSON 方式） ​

2.8 更新头像（Multipart 上传） ​

2.9 游客心跳 ​

三、聊天会话 ​

3.1 列出会话 ​

3.2 创建会话 ​

3.3 获取会话详情 ​

3.4 保存会话 ​

3.5 置顶/取消置顶会话 ​

3.6 重命名会话 ​

3.7 删除会话 ​

四、图片生成 ​

4.1 图片生成（非流式） ​

4.2 图片生成（流式 SSE） ​

4.3 图片流式断流恢复 ​

五、图片记录 ​

5.1 列出图片记录 ​

5.2 获取单条图片记录 ​

5.3 创建图片记录 ​

5.4 更新图片记录 ​

六、视频生成 ​

6.1 视频生成 ​

6.2 查询视频任务状态 ​

6.3 创建视频任务（异步 Job） ​

6.4 查询视频 Job 状态 ​

6.5 视频 Job 进度流式推送 ​

七、视频记录 ​

7.1 列出视频记录 ​

7.2 获取单条视频记录 ​

7.3 创建视频记录 ​

7.4 更新视频记录 ​

八、作品管理 ​

8.1 列出作品 ​

8.2 删除作品 ​

8.3 创建代码作品 ​

8.4 更新作品标题 ​

8.5 获取作品资产内容 ​

九、文件上传 ​

9.1 上传文件 ​

9.2 上传代码文本 ​

十、本地资产访问 ​

10.1 通过 assetId 预览资产 ​

10.2 通过编码 ID 分享资产 ​

10.3 访问本地资产文件 ​

十一、模型能力与协议 ​

11.1 解析模型图片能力矩阵 ​

11.2 解析模型协议详情 ​

11.3 列出协议配置 ​

十二、模型测试 ​

12.1 列出可用测试用例 ​

12.2 创建测试运行 ​

12.3 获取测试运行结果 ​

十三、技能 ​

NXAI 后端 API 接口文档

概述

基础信息

通用响应格式

通用状态码

一、AI 网关核心

1.1 获取模型列表

1.2 获取模型列表缓存快照

1.3 获取自动优选模型列表

1.4 设置初始分组和密钥

1.5 获取初始分组和密钥

1.6 聊天补全（非流式）

1.7 专业版聊天补全（非流式）

1.8 聊天补全（流式 SSE）

1.9 专业版聊天补全（流式 SSE）

1.10 流式断流恢复

二、认证与用户

2.1 获取公开配置

2.2 用户注册

2.3 用户登录

2.4 AI 网关 SSO 单点登录

2.5 AI（new-api）注册成功回调

2.6 获取当前用户信息

2.7 更新头像（JSON 方式）

2.8 更新头像（Multipart 上传）

2.9 游客心跳

三、聊天会话

3.1 列出会话

3.2 创建会话

3.3 获取会话详情

3.4 保存会话

3.5 置顶/取消置顶会话

3.6 重命名会话

3.7 删除会话

四、图片生成

4.1 图片生成（非流式）

4.2 图片生成（流式 SSE）

4.3 图片流式断流恢复

五、图片记录

5.1 列出图片记录

5.2 获取单条图片记录

5.3 创建图片记录

5.4 更新图片记录

六、视频生成

6.1 视频生成

6.2 查询视频任务状态

6.3 创建视频任务（异步 Job）

6.4 查询视频 Job 状态

6.5 视频 Job 进度流式推送

七、视频记录

7.1 列出视频记录

7.2 获取单条视频记录

7.3 创建视频记录

7.4 更新视频记录

八、作品管理

8.1 列出作品

8.2 删除作品

8.3 创建代码作品

8.4 更新作品标题

8.5 获取作品资产内容

九、文件上传

9.1 上传文件

9.2 上传代码文本

十、本地资产访问

10.1 通过 assetId 预览资产

10.2 通过编码 ID 分享资产

10.3 访问本地资产文件

十一、模型能力与协议

11.1 解析模型图片能力矩阵

11.2 解析模型协议详情

11.3 列出协议配置

十二、模型测试

12.1 列出可用测试用例

12.2 创建测试运行

12.3 获取测试运行结果

十三、技能

13.1 列出可用技能

十四、助手（Assistants）

14.1 列出公开助手

14.2 列出个人助手