MCP-X API 接口文档

本文档详细描述了 MCP-X 平台的所有后端 API 接口。

通用说明

Base URL

https://www.mcp-x.com/prod-api

认证方式

大部分接口需要在请求头中携带 Bearer Token：

Authorization: Bearer {token}

完整请求示例

POST https://www.mcp-x.com/prod-api/ai/video/generate

响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

错误码说明

错误码	说明
200	成功
401	认证失败/Token 过期
403	权限不足
500	服务器错误

1. 认证相关

1.1 用户登录

POST /auth/login

请求体

{
  "username": "string",  // 用户名/邮箱
  "password": "string"   // 密码
}

响应

{
  "code": 200,
  "data": {
    "access_token": "string",
    "token": "string",
    "userInfo": {
      "userId": "string",
      "username": "string",
      "nickName": "string",
      "avatar": "string"
    }
  }
}

1.2 用户注册

POST /auth/register

请求体

{
  "username": "string",  // 邮箱
  "password": "string",  // 密码
  "code": "string"       // 邮箱验证码
}

1.3 发送邮箱验证码

POST /resource/email/code

请求体

{
  "username": "string"  // 邮箱地址
}

1.4 GitHub OAuth 登录

POST /web/auth/github/login

请求体

{
  "code": "string"  // GitHub OAuth 授权码
}

2. 模型列表

2.1 获取所有模型

GET /system/model/modelList

获取平台支持的所有 AI 模型列表，包含对话、图像、视频等各类模型，可通过 category 字段区分类型。

响应

{
  "code": 200,
  "data": [
    {
      "id": "string",
      "modelName": "gpt-4o",
      "category": "text2text",
      "modelDescribe": "string",
      "modelPrice": 0,
      "modelType": "string",
      "modelShow": "string",
      "systemPrompt": null,
      "apiHost": "string",
      "remark": "string"
    }
  ]
}

category 枚举值

值	说明
text2text	对话/文本模型
text2image	图像生成模型
text2video	视频生成模型

3. 会话管理

Session 是 AI 对话、图像生成、视频生成等功能的统一上下文容器。创建 Session 后，将 sessionId 传入各业务接口即可关联上下文、保存历史记录。

3.1 新建会话

POST /web/session

请求体

{
  "userId": "string",
  "sessionContent": "",       
  "sessionTitle": "string",   
  "remark": "string",         
  "appId": "string"           
}

响应

{
  "code": 200,
  "data": "1773812492551"
}

data 为新建的 sessionId（大整数字符串）。

3.2 会话列表

GET /web/session/list

查询参数

参数	类型	说明
userId	string	用户ID
appId	string	应用ID（可选）
isDelete	number	是否删除，默认 0

响应

{
  "code": 200,
  "rows": [
    {
      "id": "string",
      "sessionTitle": "string",
      "sessionContent": "string",
      "remark": "string",
      "userId": "string",
      "createTime": "string",
      "updateTime": "string"
    }
  ]
}

3.3 获取聊天记录

GET /web/message/list

查询参数

参数	类型	说明
sessionId	string	会话ID
userId	string	用户ID

响应

{
  "code": 200,
  "rows": [
    {
      "id": "string",
      "sessionId": "string",
      "role": "user | assistant | system",
      "content": "string",
      "userId": "string",
      "modelName": "gpt-4o",
      "deductCost": "0.02",
      "totalTokens": 512,
      "createTime": "string",
      "updateTime": "string",
      "files": [
        { "uid": "string", "name": "file.pdf", "type": "application/pdf", "size": 102400, "url": "string" }
      ]
    }
  ]
}

3.4 更新会话

PUT /web/session

请求体

{
  "id": "string",
  "sessionId": "string",
  "sessionTitle": "string",
  "remark": "string"
}

id 与 sessionId 二选一传入即可。

3.5 更新会话内容

PUT /web/session/content

用于保存会话内容（如视频项目 JSON），持久化工作区状态。

请求体

{
  "id": "string",
  "content": "string",
  "sessionTitle": "string"
}

3.6 会话内容历史

GET /web/session/content/list/{sessionId}

获取会话内容的历史版本列表（如视频项目的历史快照）。

响应

{
  "code": 200,
  "rows": [
    {
      "id": "string",
      "sessionId": "string",
      "content": "string",
      "sessionTitle": "string",
      "createTime": "string"
    }
  ]
}

3.7 删除会话

DELETE /web/session/{sessionId}

软删除指定会话。

响应

{
  "code": 200,
  "msg": "操作成功"
}

4. AI 对话

4.1 发送消息（SSE 流式）

POST /chat/send

请求体

{
  "messages": [{ "role": "user", "content": "hello" }],
  "model": "gpt-4o",
  "stream": true,
  "userId": "number",
  "sessionId": "string",
  "appId": "string",
  "sysPrompt": "string",
  "isMcp": false,
  "mcpConfig": {},
  "internet": false,
  "deepResearch": false,
  "kid": "string",
  "agent": "string"
}

SSE 响应格式

data: {"choices":[{"delta":{"content":"Hello!"}}]}
data: [DONE]

4.2 带文件发送消息

POST /chat/send-with-files
Content-Type: multipart/form-data

表单参数

参数	类型	说明
file	File[]	文件列表
messages	string	JSON 格式的消息数组
model	string	模型名称
stream	string	"true"
userId	string	用户ID
sessionId	string	会话ID

5. 图像生成

5.1 文生图

POST /ai/image/generate

根据文字描述生成图像。无参考图时走文生图模型（默认 z-image-turbo）。

请求体

{
  "prompt": "cinematic portrait of a young woman",
  "model": "z-image-turbo",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-text2image",
  "size": "1024*1024",
  "watermark": false,
  "referenceMaterials": []
}

响应

{
  "code": 200,
  "data": {
    "imageUrl": "https://cdn.../result.png",
    "imageBase64": "base64..."
  }
}

5.2 参考图生图（图生图）

POST /ai/image/edit

传入一张或多张参考图时，自动切换为图生图模式（内部调用 /ai/image/edit），保持参考图的视觉风格和角色一致性。支持场景图 + 多张角色定妆照同时传入。

请求体

{
  "prompt": "Generate a cinematic shot matching this prompt: \"...\"",
  "model": "flux-dev",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-text2image",
  "size": "1280*720",
  "images": [
    { "data": "base64...", "mimeType": "image/png" },
    { "data": "base64...", "mimeType": "image/png" }
  ]
}

mask 字段不传时为全图重绘模式。

5.3 图像局部编辑（蒙版重绘）

POST /ai/image/edit

传入原图 + 蒙版 + 提示词，对蒙版区域进行局部重绘，其余区域保持不变。

请求体

{
  "prompt": "change hair color to red",
  "model": "flux-dev",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-text2image",
  "size": "1024*1024",
  "images": [
    { "data": "base64...", "mimeType": "image/png" }
  ],
  "mask": {
    "data": "base64...",
    "mimeType": "image/png"
  }
}

蒙版规则：白色 = 重绘区域，黑色 = 保留区域。

响应

{
  "code": 200,
  "data": {
    "imageUrl": "https://cdn.../edited.png"
  }
}

6. 视频生成

所有视频生成接口均使用 SSE 流式响应：

POST /ai/video/generate
Content-Type: application/json
Accept: text/event-stream

6.1 文生视频

只传 prompt，不传任何图片参数，走文生视频模式。

请求体

{
  "model": "kling-v1.6-standard",
  "prompt": "a cat running in the park",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720P",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-video-studio",
  "audio": false,
  "seed": 12345
}

SSE 响应格式

data: {"choices":[{"delta":{"content":"{\"progress\":10,\"message\":\"排队中\"}"}}]}
data: {"choices":[{"delta":{"content":"{\"progress\":60,\"message\":\"生成中\"}"}}]}
data: {"choices":[{"delta":{"content":"<video>https://cdn.../result.mp4</video>"}}]}
data: [DONE]

6.2 图生视频（起始帧）

传入 imageUrl 作为视频起始帧，AI 根据 prompt 生成后续动态画面。可传 refImages 提供角色/场景参考图增强一致性。

请求体

{
  "model": "kling-v1.6-standard",
  "prompt": "the character walks forward slowly",
  "imageUrl": "https://cdn.../start-frame.jpg",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720P",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-video-studio",
  "refImages": [
    "https://cdn.../character.jpg",
    "https://cdn.../scene.jpg"
  ],
  "audio": false,
  "audioUrl": "https://cdn.../bg.mp3"
}

6.3 首尾帧插值生成视频

同时传入 firstFrameUrl 和 lastFrameUrl，AI 在两帧之间插值生成流畅过渡视频。适合精确控制镜头起止画面。

请求体

{
  "model": "kling-v1.6-standard",
  "prompt": "smooth camera pan from left to right",
  "firstFrameUrl": "https://cdn.../start.jpg",
  "lastFrameUrl": "https://cdn.../end.jpg",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720P",
  "userId": "string",
  "sessionId": "string",
  "appId": "mcpx-video-studio",
  "seed": 42
}

SSE 响应（额外返回 lastFrameUrl，可用于下一镜头的起始帧）

data: {"choices":[{"delta":{"content":"{\"lastFrameUrl\":\"https://cdn.../last.jpg\"}"}}]}
data: {"choices":[{"delta":{"content":"<video>https://cdn.../result.mp4</video>"}}]}
data: [DONE]

6.4 可选参数说明

参数	类型	说明
audio	boolean	是否生成同步音频
audioUrl	string	背景音频文件 URL
seed	number	随机种子，用于复现结果
refImages	string[]	额外参考图（角色图、场景图等）
referenceMaterials	object[]	@功能引用的素材列表

6.5 支持的视频模型

模型名称	说明
kling-v1.6-standard	可灵标准版
kling-v1.6-pro	可灵专业版
runway-gen3	Runway Gen-3
pika-v1	Pika Labs

6.6 分辨率与宽高比

分辨率：480P / 720P / 1080P

宽高比：16:9（横屏）/ 9:16（竖屏）/ 1:1（方形）

7. 应用构建

7.1 创建应用

POST /app/webgen/add

请求体

{
  "appName": "My App",
  "message": "Create a landing page",
  "initPrompt": "string",
  "codeGenType": "REACT",
  "userId": "string"
}

codeGenType 可选值：HTML / REACT / VUE / STATIC

7.2 获取应用信息

GET /app/webgen/{appId}

7.3 获取应用列表

GET /app/webgen/list

查询参数

参数	类型	说明
pageNum	number	页码
pageSize	number	每页数量
appName	string	应用名称（可选）
isDelete	number	是否删除

7.4 对话生成代码（SSE 流式）

GET /app/webgen/chat/gen/code
Accept: text/event-stream

查询参数

参数	类型	说明
appId	string	应用ID
message	string	用户指令
stream	string	"true"

SSE 响应格式

data: {"d": "生成的代码内容"}
data: [DONE]

7.5 获取聊天历史

GET /app/webgen/chat/history

查询参数

参数	类型	说明
appId	string	应用ID
pageSize	number	每页数量
lastCreateTime	string	最后创建时间

7.6 部署应用

POST /app/webgen/deploy

请求体：直接传递应用ID字符串 "appId"

7.7 下载代码

GET /app/webgen/download/{appId}

响应为 Blob 文件。

7.8 删除应用

POST /app/webgen/delete

请求体

{ "id": "string" }

7.9 更新应用

POST /app/webgen/update

请求体

{
  "id": "string",
  "appName": "string",
  "cover": "string",
  "priority": 0
}

8. MCP 服务

8.1 获取服务列表

GET /web/mcp/server/list

8.2 获取服务详情

GET /web/mcp/server/detail/{id}

响应

{
  "code": 200,
  "data": {
    "name": "google-search",
    "chineseName": "string",
    "handle": "string",
    "descriptionEn": "string",
    "descriptionCn": "string",
    "category": "string",
    "usageCount": 0,
    "verified": false,
    "tools": ["search", "get_page_content"],
    "serverdetailVo": {
      "toolList": [],
      "envSchema": "string",
      "serverConfig": "string",
      "readme": "string",
      "readmeCn": "string"
    }
  }
}

8.3 获取首页服务

GET /web/mcp/home/server

8.4 获取分类列表

GET /web/mcp/home/category

8.5 搜索服务

GET /web/mcp/search

查询参数

参数	类型	说明
key	string	搜索关键词

8.6 添加服务

POST /web/mcp/member/addserver

请求体

{
  "name": "string",
  "handle": "string",
  "description": "string",
  "documentation": "string"
}

8.7 用户 MCP 配置

新增配置

POST /user/userMcpServer

更新配置

PUT /user/userMcpServer

获取配置列表

GET /user/userMcpServer/list

查询参数

参数	类型	说明
pageNum	number	页码，默认 1
pageSize	number	每页数量，默认 20

删除配置

DELETE /user/userMcpServer/{ids}

启动 MCP 服务

POST /user/userMcpServer/start/{ids}

9. 知识库

9.1 获取知识库列表

GET /knowledge/list

获取用户的知识库列表。

查询参数

参数	类型	说明
pageNum	number	页码
pageSize	number	每页数量

9.2 新增知识库

POST /knowledge/save

9.3 编辑知识库

POST /knowledge/edit

9.4 删除知识库

POST /knowledge/remove/{id}

9.5 获取知识库附件

GET /knowledge/detail/{id}

9.6 上传附件

POST /knowledge/attach/upload
Content-Type: multipart/form-data

上传文档到知识库。

表单参数

参数	类型	说明
file	File	文档文件
kid	string	知识库ID

9.7 删除附件

POST /knowledge/attach/remove/{kid}

9.8 获取知识片段

GET /knowledge/fragment/list/{docId}

9.9 文件翻译

POST /knowledge/translationByFile
Content-Type: multipart/form-data

表单参数

参数	类型	说明
file	File	文件
targetLanguage	string	目标语言

10. 支付系统

10.1 获取 VIP 套餐

GET /web/package/vip

获取所有可用的 VIP 订阅套餐。

10.2 创建微信支付订单

POST /web/pay/wechat/create

请求体

{ "planId": 1 }

10.3 继续微信支付

POST /web/pay/wechat/continue

请求体

{ "orderNo": "string" }

10.4 查询订单详情

GET /web/pay/order/detail/{orderNo}

10.5 获取订单列表

GET /web/pay/order/list

查询参数

参数	类型	说明
pageNum	number	页码
pageSize	number	每页数量

10.6 获取余额和套餐信息

GET /web/pay/me/balance-plan

11. 其他接口

11.1 上传文件到 OSS

POST /public/oss/upload
Content-Type: multipart/form-data

表单参数

参数	类型	说明
file	File	要上传的文件

响应

{
  "code": 200,
  "data": {
    "url": "string",
    "fileName": "string",
    "ossId": "string"
  }
}

11.2 提交反馈

POST /web/feedback/submit

请求体

{
  "contactInfo": "string",
  "contributionDescription": "string",
  "detailedDescription": "string",
  "feedbackType": "number",
  "githubForkUrl": "string",
  "issueType": "string",
  "releaseUrl": "string"
}

11.3 获取我的反馈

GET /web/feedback/my

也可用于验证 Token 有效性。

11.4 联系我们

POST /web/contact

请求体

{
  "name": "string",
  "email": "string",
  "subject": "string",
  "message": "string"
}

11.5 获取 AI 查询结果（参考链接）

GET /web/ai-query/results/{queryId}/page

查询参数

参数	类型	说明
pageNum	number	页码
pageSize	number	每页数量

11.6 Agent 市场

获取分类列表

GET /web/agent/categories

获取 Agent 列表

GET /web/agent/list

查询参数

参数	类型	说明
pageNum	number	页码
pageSize	number	每页数量
categoryId	number	分类ID（可选）
status	number	状态，默认 1

获取 Agent 详情

GET /web/agent/detail/{id}

搜索 Agent

GET /web/agent/search

查询参数

参数	类型	说明
key	string	搜索关键词
pageNum	number	页码
pageSize	number	每页数量

获取精选 Agent

GET /web/agent/featured

获取最新 Agent

GET /web/agent/recent

按分类获取 Agent

GET /web/agent/category/{categoryId}

记录 Agent 活动

GET /web/agent/activity/{id}

文档版本：2.0.0
更新时间：2026-03-13

FilesExpand file tree

API_DOCUMENTATION.md

Latest commit

History

API_DOCUMENTATION.md

File metadata and controls

MCP-X API 接口文档

目录

通用说明

Base URL

认证方式

完整请求示例

响应格式

错误码说明

1. 认证相关

1.1 用户登录

1.2 用户注册

1.3 发送邮箱验证码

1.4 GitHub OAuth 登录

2. 模型列表

2.1 获取所有模型

3. 会话管理

3.1 新建会话

3.2 会话列表

3.3 获取聊天记录

3.4 更新会话

3.5 更新会话内容

3.6 会话内容历史

3.7 删除会话

4. AI 对话

4.1 发送消息（SSE 流式）

4.2 带文件发送消息

5. 图像生成

5.1 文生图

5.2 参考图生图（图生图）

5.3 图像局部编辑（蒙版重绘）

6. 视频生成

6.1 文生视频

6.2 图生视频（起始帧）

6.3 首尾帧插值生成视频

6.4 可选参数说明

6.5 支持的视频模型

6.6 分辨率与宽高比

7. 应用构建

7.1 创建应用

7.2 获取应用信息

7.3 获取应用列表

7.4 对话生成代码（SSE 流式）

7.5 获取聊天历史

7.6 部署应用

7.7 下载代码

7.8 删除应用

7.9 更新应用

8. MCP 服务

8.1 获取服务列表

8.2 获取服务详情

8.3 获取首页服务

8.4 获取分类列表

8.5 搜索服务

8.6 添加服务

8.7 用户 MCP 配置

新增配置

更新配置

获取配置列表

删除配置

启动 MCP 服务

9. 知识库

9.1 获取知识库列表

9.2 新增知识库

9.3 编辑知识库

9.4 删除知识库

9.5 获取知识库附件

9.6 上传附件

9.7 删除附件

9.8 获取知识片段

9.9 文件翻译

10. 支付系统

10.1 获取 VIP 套餐

10.2 创建微信支付订单

10.3 继续微信支付