NXAI 前端 API 封装文档

概述

本文档描述 NXAI 前端项目中封装的 API 请求方法，基于 Vue.js + Axios 实现。

请求封装层

前端所有 API 请求均通过 [request.js](file:///Users/long/GitHub/nxaitest/nxaitest-frontend/src/common/request.js) 封装，具备以下特性：

特性	说明
自动 Token 注入	请求拦截器自动在 Header 添加 `token`
全局 Loading	默认显示加载进度条，可通过 `hideLoading: true` 关闭
统一错误处理	根据后端返回的 `type` 字段自动显示通知
超时处理	默认超时 8000ms，可通过 `timeout` 自定义
登录态失效处理	`type=5` 时自动清除 Token 并跳转首页

响应拦截处理

type 值	含义	前端行为
0	无提示	静默处理
1	info 提示	显示蓝色信息通知
2	success 提示	显示绿色成功通知
3	warning 提示	显示黄色警告通知
4	error 提示	显示红色错误通知
5	需重定向登录	清除 Token，跳转首页

一、用户认证模块

1.1 注册相关

`registerByEmail(email, username, password)`

说明：邮箱注册

参数：

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

对应接口：POST /api/auth/register

`getAuthPublicConfig()`

说明：获取公开配置（是否开放注册、主站注册 URL）

对应接口：GET /api/auth/public-config

1.2 登录相关

`loginByEmail(email, password)`

说明：邮箱登录

参数：

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

对应接口：POST /api/auth/login

响应示例：

json

{
  "statusCode": 2200,
  "data": {
    "token": "jwt_token",
    "user": { "id": 1, "username": "test" }
  }
}

`exchangeGatewaySso(ssoToken)`

说明：AI 网关 JWT 兑换本站登录

参数：

参数	类型	必填	说明
ssoToken	string	是	网关签发的短期 JWT

对应接口：POST /api/auth/sso/gateway

配置：timeout: 15000ms，hideLoading: true

1.3 用户信息

`getCurrentUser()`

说明：获取当前登录用户信息

对应接口：GET /api/auth/me

`updateAvatarByBase64(imageBase64)`

说明：通过 Base64 更新头像

参数：

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

对应接口：PATCH /api/auth/me/avatar

配置：timeout: 60000ms

1.4 游客心跳

`guestHeartbeat(temporaryUserId)`

说明：游客模式心跳保活

参数：

参数	类型	必填	说明
temporaryUserId	string	是	临时用户 ID

对应接口：POST /api/auth/guest/heartbeat

二、API 访问令牌

2.1 令牌管理

`listAccessTokens()`

说明：列出用户的 API 访问令牌

对应接口：GET /api/access/tokens

`ensureDefaultAccessToken()`

说明：幂等创建默认令牌（进入令牌页时调用）

对应接口：POST /api/access/tokens/ensure-default

`createAccessToken(payload)`

说明：创建新令牌

参数：

参数	类型	必填	说明
payload	object	否	令牌配置（name、modelLimits 等）

对应接口：POST /api/access/tokens

`updateAccessTokenStatus(tokenId, active)`

说明：更新令牌状态（启用/禁用）

参数：

参数	类型	必填	说明
tokenId	number/string	是	令牌 ID
active	boolean	是	是否启用

对应接口：PATCH /api/access/tokens/{tokenId}/status

`deleteAccessToken(tokenId)`

说明：删除令牌

参数：

参数	类型	必填	说明
tokenId	number/string	是	令牌 ID

对应接口：DELETE /api/access/tokens/{tokenId}

2.2 临时令牌

`getTemporaryAccessToken(temporaryUserId)`

说明：获取临时令牌

参数：

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

对应接口：GET /api/access/tokens/temporary

`upsertTemporaryAccessToken(payload)`

说明：创建/更新临时令牌

参数：

参数	类型	必填	说明
payload	object	否	包含 temporaryUserId、apiKey 等

对应接口：POST /api/access/tokens/temporary

2.3 访问日志

`getAccessUsageLogs(params)`

说明：查询 API 使用日志

参数：

参数	类型	必填	说明
params	object	否	查询参数（type、page、pageSize、时间范围等）

对应接口：GET /api/access/logs

`getAccessUsageLogStat(params)`

说明：获取 API 使用统计

参数：

参数	类型	必填	说明
params	object	否	查询参数（type、时间范围等）

对应接口：GET /api/access/logs/stat

三、聊天会话

3.1 会话管理

`listChatSessions()`

说明：列出用户会话列表

对应接口：GET /api/chat/sessions

`createChatSession(payload)`

说明：创建新会话

参数：

参数	类型	必填	说明
payload	string/object	否	会话标题或完整配置对象

对应接口：POST /api/chat/sessions

`getChatSessionDetail(sessionId)`

说明：获取会话详情

参数：

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

对应接口：GET /api/chat/sessions/{sessionId}

配置：timeout: 30000ms

`saveChatSession(sessionId, payload)`

说明：保存会话

参数：

参数	类型	必填	说明
sessionId	number/string	是	会话 ID
payload	object	否	会话数据

对应接口：PUT /api/chat/sessions/{sessionId}

`pinChatSession(sessionId, pinned)`

说明：置顶/取消置顶会话

参数：

参数	类型	必填	说明
sessionId	number/string	是	会话 ID
pinned	boolean	是	是否置顶

对应接口：PATCH /api/chat/sessions/{sessionId}/pin

`renameChatSession(sessionId, title)`

说明：重命名会话

参数：

参数	类型	必填	说明
sessionId	number/string	是	会话 ID
title	string	是	新标题

对应接口：PATCH /api/chat/sessions/{sessionId}/title

`deleteChatSession(sessionId)`

说明：删除会话

参数：

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

对应接口：DELETE /api/chat/sessions/{sessionId}

四、AI 网关核心

4.1 模型管理

`getAiModels(apiKey, baseUrl, forceRefresh, sessionId, groupName, temporaryUserId, hideLoading)`

说明：获取模型列表

参数：

参数	类型	必填	说明
apiKey	string	否	API 密钥
baseUrl	string	否	基础 URL
forceRefresh	boolean	否	是否强制刷新缓存，默认 false
sessionId	string	否	会话 ID
groupName	string	否	分组名称
temporaryUserId	string	否	临时用户 ID
hideLoading	boolean	否	是否隐藏加载状态

对应接口：POST /api/ai/models

`getInitGroupAndKey(sessionId)`

说明：获取初始分组和密钥

参数：

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

对应接口：GET /api/ai/initGroupAndKey

`getAutoPreferredModels(capability)`

说明：获取自动优选模型列表

参数：

参数	类型	必填	说明
capability	string	否	能力过滤，默认 "TEXT"

对应接口：GET /api/ai/auto/preferred-models

4.2 聊天补全

`chatCompletions(payload, options)`

说明：聊天补全（非流式）

参数：

参数	类型	必填	说明
payload	object	是	聊天请求体（model、messages 等）
options	object	否	配置选项
└─ timeout	number	否	超时时间（毫秒）
└─ suppressNotify	boolean	否	是否禁用通知
└─ hideLoading	boolean	否	是否隐藏加载状态

对应接口：POST /api/ai/chat/completions

`proChatCompletions(payload, options)`

说明：专业版聊天补全（非流式）

参数：同 chatCompletions

对应接口：POST /api/ai/pro/chat/completions

4.3 模型协议与能力

`resolveModelProtocol(modelId, scene)`

说明：解析模型协议详情

参数：

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

对应接口：GET /api/ai/model-protocol/resolve

`resolveImageModelCapability(modelId)`

说明：解析模型的图片能力矩阵

参数：

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

对应接口：GET /api/ai/model-capability/image/resolve

`listSkills(scene)`

说明：列出可用技能

参数：

参数	类型	必填	说明
scene	string	否	场景，默认 "chat"

对应接口：GET /api/ai/skills

4.4 Agent 智能体

`agentPromptPolish(payload, options)`

说明：提示词润色

参数：

参数	类型	必填	说明
payload	object	是	请求体（prompt、targetLanguage 等）
options	object	否	配置选项（同 chatCompletions）

对应接口：POST /api/agents/prompt-polish

五、视频生成

`videoGenerations(payload)`

说明：视频生成

参数：

参数	类型	必填	说明
payload	object	是	视频生成请求体

对应接口：POST /api/video/generations

`videoTaskStatus(taskId, payload)`

说明：查询视频任务状态

参数：

参数	类型	必填	说明
taskId	string	是	任务 ID
payload	object	是	查询参数

对应接口：POST /api/video/generations/{taskId}

`createVideoJob(payload)`

说明：创建视频任务（异步）

参数：

参数	类型	必填	说明
payload	object	是	视频生成请求体

对应接口：POST /api/video/jobs

`getVideoJobStatus(jobId)`

说明：查询视频 Job 状态

参数：

参数	类型	必填	说明
jobId	string	是	Job ID

对应接口：POST /api/video/jobs/{jobId}

`getVideoJobStreamUrl(jobId)`

说明：获取视频 Job 进度流 URL

参数：

参数	类型	必填	说明
jobId	string	是	Job ID

返回：完整的 SSE 流 URL

六、图片生成

`imageGenerations(payload)`

说明：图片生成（非流式）

参数：

参数	类型	必填	说明
payload	object	是	图片生成请求体

对应接口：POST /api/image/generations

`getImageGenerationStreamUrl()`

说明：获取图片生成流式 URL

返回：完整的 SSE 流 URL

对应接口：POST /api/image/generations/stream

七、图片记录

`listImageRecords()`

说明：列出图片记录

对应接口：GET /api/image/records

`getImageRecord(recordId)`

说明：获取单条图片记录

参数：

参数	类型	必填	说明
recordId	number/string	是	记录 ID

对应接口：GET /api/image/records/{recordId}

`createImageRecord(payload)`

说明：创建图片记录

参数：

参数	类型	必填	说明
payload	object	否	记录数据

对应接口：POST /api/image/records

`updateImageRecord(recordId, payload)`

说明：更新图片记录

参数：

参数	类型	必填	说明
recordId	number/string	是	记录 ID
payload	object	否	更新数据

对应接口：PUT /api/image/records/{recordId}

八、视频记录

`listVideoRecords()`

说明：列出视频记录

对应接口：GET /api/video/records

`getVideoRecord(recordId)`

说明：获取单条视频记录

参数：

参数	类型	必填	说明
recordId	number/string	是	记录 ID

对应接口：GET /api/video/records/{recordId}

`createVideoRecord(payload)`

说明：创建视频记录

参数：

参数	类型	必填	说明
payload	object	否	记录数据

对应接口：POST /api/video/records

`updateVideoRecord(recordId, payload)`

说明：更新视频记录

参数：

参数	类型	必填	说明
recordId	number/string	是	记录 ID
payload	object	否	更新数据

对应接口：PUT /api/video/records/{recordId}

九、作品管理

`listUserWorks(params)`

说明：列出作品

参数：

参数	类型	必填	说明
params	object	否	查询参数（scene、limit、offset、temporaryUserId）

对应接口：GET /api/works

`deleteUserWork(workId, params)`

说明：删除作品

参数：

参数	类型	必填	说明
workId	number/string	是	作品 ID
params	object	否	额外参数（temporaryUserId）

对应接口：DELETE /api/works/{workId}

`createCodeWork(params)`

说明：创建代码作品

参数：

参数	类型	必填	说明
params	object	是	作品数据（title、description、assetIds 等）

对应接口：POST /api/works/code

`updateWorkTitle(params)`

说明：更新作品标题

参数：

参数	类型	必填	说明
params	object	是	包含 workId 和 title

对应接口：PUT /api/works/{workId}/title

十、文件上传

`uploadGeneratedFile(formData)`

说明：上传生成的文件

参数：

参数	类型	必填	说明
formData	FormData	是	包含 file 字段的表单数据

对应接口：POST /api/files/upload

配置：Content-Type: multipart/form-data，timeout: 30000ms

`uploadCodeText(params)`

说明：上传代码文本

参数：

参数	类型	必填	说明
params	object	是	包含 codeContent、language、filename

对应接口：POST /api/files/upload-text

十一、Vibe Coding

`vibeCodingCreateSession(payload)`

说明：创建 Vibe Coding 会话

参数：

参数	类型	必填	说明
payload	object	是	会话配置（giteeToken、repoName、projectDescription 等）

对应接口：POST /api/vibe-coding/sessions

`vibeCodingGetStreamUrl(sessionId)`

说明：获取 Vibe Coding 流 URL

参数：

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

返回：完整的 SSE 流 URL

`vibeCodingRespondToPrompt(sessionId, response)`

说明：响应 Vibe Coding 提示

参数：

参数	类型	必填	说明
sessionId	string	是	会话 ID
response	string	是	用户响应内容

对应接口：POST /api/vibe-coding/sessions/{sessionId}/respond

`vibeCodingAbortSession(sessionId)`

说明：中止 Vibe Coding 会话

参数：

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

对应接口：POST /api/vibe-coding/sessions/{sessionId}/abort

`vibeCodingGetSessionStatus(sessionId)`

说明：获取 Vibe Coding 会话状态

参数：

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

对应接口：GET /api/vibe-coding/sessions/{sessionId}/status

十二、助手（Assistants）

`listPublicAssistants()`

说明：列出公开助手（无需登录）

对应接口：GET /api/assistants/public

`listPersonalAssistants()`

说明：列出个人助手（需登录）

对应接口：GET /api/assistants/personal

`listCommunityAssistants()`

说明：列出社区助手

对应接口：GET /api/assistants/list-community

`getAssistantDetail(id)`

说明：获取助手详情

参数：

参数	类型	必填	说明
id	number/string	是	助手 ID

对应接口：GET /api/assistants/{id}

`createAssistant(payload)`

说明：创建助手

参数：

参数	类型	必填	说明
payload	object	是	助手配置（name、description、systemPrompt 等）

对应接口：POST /api/assistants

`updateAssistant(payload)`

说明：更新助手

参数：

参数	类型	必填	说明
payload	object	是	包含 id 和更新字段

对应接口：PUT /api/assistants

`deleteAssistant(id)`

说明：删除助手

参数：

参数	类型	必填	说明
id	number/string	是	助手 ID

对应接口：DELETE /api/assistants/{id}

`shareAssistant(payload)`

说明：分享/取消分享助手

参数：

参数	类型	必填	说明
payload	object	是	包含 id 和 share（boolean）

对应接口：POST /api/assistants/share

`getSharedAssistant(shareCode)`

说明：获取分享的助手

参数：

参数	类型	必填	说明
shareCode	string	是	分享码

对应接口：GET /api/assistants/shared/{shareCode}

`importSharedAssistant(shareCode)`

说明：导入分享的助手

参数：

参数	类型	必填	说明
shareCode	string	是	分享码

对应接口：POST /api/assistants/import/{shareCode}

十三、模型测试（独立模块）

模型测试 API 使用独立的 axios 实例，封装在 [modelTestRequest.js](file:///Users/long/GitHub/nxaitest/nxaitest-frontend/src/network/modelTestRequest.js)

`createModelTestRun(payload)`

说明：创建测试运行

参数：

参数	类型	必填	说明
payload	object	是	测试配置（testSuiteId、model、testCases 等）

对应接口：POST /api/model-test/runs

`getModelTestRun(runId)`

说明：获取测试运行结果

参数：

参数	类型	必填	说明
runId	string	是	运行 ID

对应接口：GET /api/model-test/runs/{runId}

`getModelTestCases(target, modelId)`

说明：列出可用测试用例

参数：

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

对应接口：GET /api/model-test/cases

请求配置选项

所有请求方法均支持以下可选配置项：

选项	类型	默认值	说明
hideLoading	boolean	false	是否隐藏加载进度条
suppressNotify	boolean	false	是否禁用通知提示
timeout	number	8000	超时时间（毫秒）

示例：

javascript

userRequest.chatCompletions(payload, {
  timeout: 30000,
  hideLoading: true,
  suppressNotify: true
});

前端路由

前端使用 Vue Router，定义了以下页面路由：

路径	页面组件	说明
`/home`	HomePage	首页
`/chat`	TextChat	文本聊天
`/create`	CreateStudio	创作工作室
`/agent-design`	AgentDesign	Agent 设计
`/api-center`	ApiPage	API 中心
`/api-center/guide/:id`	GuideDetailPage	API 指南详情
`/events`	EventsPage	活动页
`/team`	TeamPage	团队页
`/modeltest`	ModelTest	模型测试
`/account/settings`	UserAccountSettings	账户设置
`/account/subscription`	MembershipStaticPage	会员订阅
`/gallery`	GalleryPage	作品画廊
`/assistants/library`	AssistantLibrary	助手库
`/assistants/create`	AssistantEditor	创建助手
`/assistants/edit/:id`	AssistantEditor	编辑助手
`/assistants/share/:shareCode`	AssistantDetail	分享的助手详情

基础聊天(ChatCompletions格式)

会话聊天(Responses格式)

OpenAI聊天格式

Gemini原生格式

NXAI 前端 API 封装文档 ​

概述 ​

请求封装层 ​

响应拦截处理 ​

一、用户认证模块 ​

1.1 注册相关 ​

registerByEmail(email, username, password) ​

getAuthPublicConfig() ​

1.2 登录相关 ​

loginByEmail(email, password) ​

exchangeGatewaySso(ssoToken) ​

1.3 用户信息 ​

getCurrentUser() ​

updateAvatarByBase64(imageBase64) ​

1.4 游客心跳 ​

guestHeartbeat(temporaryUserId) ​

二、API 访问令牌 ​

2.1 令牌管理 ​

listAccessTokens() ​

ensureDefaultAccessToken() ​

createAccessToken(payload) ​

updateAccessTokenStatus(tokenId, active) ​

deleteAccessToken(tokenId) ​

2.2 临时令牌 ​

getTemporaryAccessToken(temporaryUserId) ​

upsertTemporaryAccessToken(payload) ​

2.3 访问日志 ​

getAccessUsageLogs(params) ​

getAccessUsageLogStat(params) ​

三、聊天会话 ​

3.1 会话管理 ​

listChatSessions() ​

createChatSession(payload) ​

getChatSessionDetail(sessionId) ​

saveChatSession(sessionId, payload) ​

pinChatSession(sessionId, pinned) ​

renameChatSession(sessionId, title) ​

deleteChatSession(sessionId) ​

四、AI 网关核心 ​

4.1 模型管理 ​

getAiModels(apiKey, baseUrl, forceRefresh, sessionId, groupName, temporaryUserId, hideLoading) ​

getInitGroupAndKey(sessionId) ​

getAutoPreferredModels(capability) ​

4.2 聊天补全 ​

chatCompletions(payload, options) ​

proChatCompletions(payload, options) ​

4.3 模型协议与能力 ​

resolveModelProtocol(modelId, scene) ​

resolveImageModelCapability(modelId) ​

listSkills(scene) ​

4.4 Agent 智能体 ​

agentPromptPolish(payload, options) ​

五、视频生成 ​

videoGenerations(payload) ​

videoTaskStatus(taskId, payload) ​

createVideoJob(payload) ​

getVideoJobStatus(jobId) ​

getVideoJobStreamUrl(jobId) ​

六、图片生成 ​

imageGenerations(payload) ​

getImageGenerationStreamUrl() ​

七、图片记录 ​

listImageRecords() ​

getImageRecord(recordId) ​

createImageRecord(payload) ​

updateImageRecord(recordId, payload) ​

八、视频记录 ​

listVideoRecords() ​

getVideoRecord(recordId) ​

createVideoRecord(payload) ​

updateVideoRecord(recordId, payload) ​

九、作品管理 ​

listUserWorks(params) ​

deleteUserWork(workId, params) ​

createCodeWork(params) ​

updateWorkTitle(params) ​

NXAI 前端 API 封装文档

概述

请求封装层

响应拦截处理

一、用户认证模块

1.1 注册相关

`registerByEmail(email, username, password)`

`getAuthPublicConfig()`

1.2 登录相关

`loginByEmail(email, password)`

`exchangeGatewaySso(ssoToken)`

1.3 用户信息

`getCurrentUser()`

`updateAvatarByBase64(imageBase64)`

1.4 游客心跳

`guestHeartbeat(temporaryUserId)`

二、API 访问令牌

2.1 令牌管理

`listAccessTokens()`

`ensureDefaultAccessToken()`

`createAccessToken(payload)`

`updateAccessTokenStatus(tokenId, active)`

`deleteAccessToken(tokenId)`

2.2 临时令牌

`getTemporaryAccessToken(temporaryUserId)`

`upsertTemporaryAccessToken(payload)`

2.3 访问日志

`getAccessUsageLogs(params)`

`getAccessUsageLogStat(params)`

三、聊天会话

3.1 会话管理

`listChatSessions()`

`createChatSession(payload)`

`getChatSessionDetail(sessionId)`

`saveChatSession(sessionId, payload)`

`pinChatSession(sessionId, pinned)`

`renameChatSession(sessionId, title)`

`deleteChatSession(sessionId)`

四、AI 网关核心

4.1 模型管理

`getAiModels(apiKey, baseUrl, forceRefresh, sessionId, groupName, temporaryUserId, hideLoading)`

`getInitGroupAndKey(sessionId)`

`getAutoPreferredModels(capability)`

4.2 聊天补全

`chatCompletions(payload, options)`

`proChatCompletions(payload, options)`

4.3 模型协议与能力

`resolveModelProtocol(modelId, scene)`

`resolveImageModelCapability(modelId)`

`listSkills(scene)`

4.4 Agent 智能体

`agentPromptPolish(payload, options)`

五、视频生成

`videoGenerations(payload)`

`videoTaskStatus(taskId, payload)`

`createVideoJob(payload)`

`getVideoJobStatus(jobId)`

`getVideoJobStreamUrl(jobId)`

六、图片生成

`imageGenerations(payload)`

`getImageGenerationStreamUrl()`

七、图片记录

`listImageRecords()`

`getImageRecord(recordId)`

`createImageRecord(payload)`

`updateImageRecord(recordId, payload)`

八、视频记录

`listVideoRecords()`

`getVideoRecord(recordId)`

`createVideoRecord(payload)`

`updateVideoRecord(recordId, payload)`

九、作品管理

`listUserWorks(params)`

`deleteUserWork(workId, params)`

`createCodeWork(params)`

`updateWorkTitle(params)`

十、文件上传

`uploadGeneratedFile(formData)`

`uploadCodeText(params)`

十一、Vibe Coding