MomoHubDocs
API文档

AI 角色

AI 角色管理 API

获取公开角色列表

GET/characters/public

获取所有公开角色，支持分页。

查询参数：

page
string
页码，从 1 开始
limit
string
每页数量，1-100

响应数据：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "items": [
      {
        "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
        "author": {
          "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
          "name": "Alice",
          "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
        },
        "name": "白洲梓",
        "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png",
        "bio": "Vanitas Vanitatum Et Omnia Vanitas",
        "originPrompt": "",
        "isPublic": true,
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-15T08:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": "2026-01-15T08:30:00Z"
}

响应状态码：

状态码说明
200获取成功
400分页参数无效

搜索角色

GET/characters/search Auth

按名称搜索角色，返回公开角色及自己的私有角色。

查询参数：

q
string
搜索关键词
page
string
页码，从 1 开始
limit
string
每页数量，1-100

响应数据：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "items": [
      {
        "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
        "author": {
          "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
          "name": "Alice",
          "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
        },
        "name": "白洲梓",
        "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png",
        "bio": "Vanitas Vanitatum Et Omnia Vanitas",
        "originPrompt": "",
        "isPublic": true,
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-15T08:30:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  },
  "timestamp": "2026-01-15T08:30:00Z"
}

响应状态码：

状态码说明
200搜索成功
400查询参数无效
401Token 无效

获取我的角色列表

GET/characters Auth

获取当前登录用户创建的所有角色，支持分页。

查询参数：

page
string
页码，从 1 开始
limit
string
每页数量，1-100

响应数据：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "items": [
      {
        "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
        "author": {
          "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
          "name": "Alice",
          "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
        },
        "name": "白洲梓",
        "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png",
        "bio": "Vanitas Vanitatum Et Omnia Vanitas",
        "originPrompt": "",
        "isPublic": true,
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-15T08:30:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  },
  "timestamp": "2026-01-15T08:30:00Z"
}

响应状态码：

状态码说明
200获取成功
400分页参数无效
401未登录或令牌无效

获取角色详情

GET/characters/{characterId}

获取指定角色的详细信息。公开角色无需认证，私有角色需要是作者。

响应数据：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
    "author": {
      "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
      "name": "Alice",
      "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
    },
    "name": "白洲梓",
    "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png",
    "bio": "Vanitas Vanitatum Et Omnia Vanitas",
    "originPrompt": "",
    "isPublic": true,
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-15T08:30:00Z"
  },
  "timestamp": "2026-01-15T08:30:00Z"
}

响应状态码：

状态码说明
200获取成功
403权限不足
404角色不存在

创建角色

POST/characters Auth

创建一个新的 AI 角色。

请求参数：

name
string required
角色名称
avatar
string
头像 URL
bio
string
角色简介
originPrompt
string
角色系统提示词
isPublic
boolean
是否公开，默认 false

响应数据：

{
  "success": true,
  "message": "角色创建成功",
  "data": {
    "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
    "author": {
      "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
      "name": "Alice",
      "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
    },
    "name": "白洲梓",
    "avatar": null,
    "bio": "Vanitas Vanitatum Et Omnia Vanitas",
    "originPrompt": "",
    "isPublic": true,
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  },
  "timestamp": "2026-01-01T00:00:00Z"
}

响应状态码：

状态码说明
201创建成功
400输入参数无效
401未登录或令牌无效

更新角色

PUT/characters/{characterId} Auth

更新指定角色的信息，需要是角色的作者。

请求参数：

name
string required
角色名称
avatar
string
头像 URL
bio
string
角色简介
originPrompt
string
角色系统提示词
isPublic
boolean
是否公开

响应数据：

{
  "success": true,
  "message": "角色更新成功",
  "data": {
    "id": "967217c8-4e26-4404-bcc4-03e084b5d6f9",
    "author": {
      "id": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
      "name": "Alice",
      "avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.png"
    },
    "name": "白洲梓",
    "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png",
    "bio": "Vanitas Vanitatum Et Omnia Vanitas",
    "originPrompt": "",
    "isPublic": true,
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-20T10:00:00Z"
  },
  "timestamp": "2026-01-20T10:00:00Z"
}

响应状态码：

状态码说明
200更新成功
400输入参数无效
401未登录或令牌无效
403权限不足
404角色不存在

删除角色

DELETE/characters/{characterId} Auth

永久删除指定角色，需要是角色的作者。此操作不可撤销。

响应状态码：

状态码说明
204删除成功
401未登录或令牌无效
403权限不足
404角色不存在

上传角色头像

POST/characters/{characterId}/avatar Auth

通过 multipart/form-data 上传角色头像。

请求参数：

file
binary required
头像图片文件

响应数据：

{
  "success": true,
  "message": "头像上传成功",
  "data": {
    "avatar": "https://cdn-momohub.hanasaki.tech/avatars/967217c8-4e26-4404-bcc4-03e084b5d6f9.png"
  },
  "timestamp": "2026-01-20T10:00:00Z"
}

响应状态码：

状态码说明
200上传成功
400未上传文件
401未登录或令牌无效

链接知识库到角色

POST/characters/{characterId}/knowledge-bases Auth

将指定知识库关联到角色，需要是角色的作者。

请求参数：

knowledgeBaseId
string required
知识库 ID（UUID 格式）
priority
integer
优先级

响应状态码：

状态码说明
200关联成功
401未登录或令牌无效
403权限不足
404角色不存在

获取角色关联的知识库列表

GET/characters/{characterId}/knowledge-bases

获取指定角色订阅的所有知识库列表。

响应数据：

{
  "success": true,
  "message": "操作成功",
  "data": [
    {
      "knowledgeBaseId": "660e8400-e29b-41d4-a716-446655440000",
      "priority": 1
    },
    {
      "knowledgeBaseId": "770e8400-e29b-41d4-a716-446655440000",
      "priority": 2
    }
  ],
  "timestamp": "2026-01-20T10:00:00Z"
}

响应状态码：

状态码说明
200获取成功
401Token 无效
403权限不足
404角色不存在

解除角色与知识库的链接

DELETE/characters/{characterId}/knowledge-bases/{knowledgeBaseId} Auth

移除角色与指定知识库的关联关系，需要是角色的作者。

响应状态码：

状态码说明
204解除关联成功
401未登录或令牌无效
403权限不足
404角色不存在

用户认证

用户认证相关 API

知识库

知识库管理 API