AI角色添加接口

用于在指定应用中创建新的AI角色，支持动态身份验证（令牌启用时通过token验证，令牌未启用时通过user+pass验证），包含开发者状态、应用状态及VIP权限校验机制。

请求地址 GET / POST

https://nobase.cn/api/ai/role_add

请求参数

参数名	位置	类型	必选	说明
appid	query	string	✅ 是	应用唯一标识，从开发者中心获取
name	query	string	✅ 是	角色名称，AI角色的显示名称（如“编程助手”“法律顾问”）
roles	query	string	✅ 是	角色描述，定义AI角色的行为模式、性格特点及功能范围
imag	query	string	✅ 是	角色头像URL，用于前端展示角色形象
sex	query	number	✅ 是	角色性别标识（1=男，2=女，0=未知）
type	query	number	✅ 是	角色类型标识，用于区分角色所属类别（如1=通用型，2=专业型）
token	query	string	条件必选	用户令牌，仅令牌启用（应用配置为token验证）时需传递
user	query	string	条件必选	用户账号，仅令牌未启用（应用配置为账号密码验证）时需传递
pass	query	string	条件必选	用户密码，仅令牌未启用（应用配置为账号密码验证）时需传递

返回示例

成功响应（角色添加成功）

{
  "code": 200,
  "msg": "添加成功！"
}

失败响应（参数问题）

{
  "code": 204,
  "msg": "接口参数错误：缺少appid"
}

{
  "code": 204,
  "msg": "接口参数错误：缺少name"
}

{
  "code": 204,
  "msg": "接口参数错误：无效的appid或未找到关联的开发者信息"
}

{
  "code": 204,
  "msg": "接口参数错误：缺少token"
}

{
  "code": 204,
  "msg": "接口参数错误：缺少user或pass"
}

失败响应（身份验证异常）

{
  "code": 401,
  "msg": "token无效或已过期"
}

{
  "code": 401,
  "msg": "token信息不完整"
}

{
  "code": 407,
  "msg": "用户账户不存在或验证失败！"
}

失败响应（状态/权限异常）

{
  "code": 404,
  "msg": "开发者账号未注册！"
}

{
  "code": 404,
  "msg": "应用不存在！"
}

{
  "code": 407,
  "msg": "应用配置不存在！"
}

{
  "code": 404,
  "msg": "开发者账号状态异常！"
}

{
  "code": 404,
  "msg": "应用已停用"
}

{
  "code": 404,
  "msg": "应用审核中！"
}

{
  "code": 404,
  "msg": "开发者账号已逾期(30天),请缴费之后重试！"
}

{
  "code": 400,
  "msg": "账号会员已过期，请续费"
}

失败响应（业务处理异常）

{
  "code": 409,
  "msg": "添加失败！"
}

返回数据结构

参数名	类型	说明
code	number	状态码：200=添加成功；204=参数缺失/错误；401=token无效/过期/不完整；404=开发者/应用状态异常/账号未注册/应用不存在；407=应用配置不存在/用户验证失败；400=会员过期；409=添加失败
msg	string	响应信息：成功时为添加结果提示；失败时为错误原因说明

代码示例

JavaScript（令牌启用，token验证）

// 令牌启用时添加AI角色
const params = new URLSearchParams({
  appid: "your_app_id",
  name: "数学导师",
  roles: "你是一名专业数学导师，擅长解答中小学数学问题",
  imag: "https://example.com/avatar/math_teacher.png",
  sex: 1,
  type: 2,
  token: "valid_user_token"
});

fetch("https://nobase.cn/api/ai/role_add", {
  method: "POST",
  body: params,
  headers: { "Content-Type": "application/x-www-form-urlencoded" }
})
.then(res => res.json())
.then(res => {
  if (res.code === 200) {
    console.log("角色添加成功");
  } else {
    console.error("添加失败：", res.msg);
  }
});

JavaScript（令牌未启用，user+pass验证）

// 令牌未启用时添加AI角色
const url = new URL("https://nobase.cn/api/ai/role_add");
url.searchParams.set("appid", "your_app_id");
url.searchParams.set("name", "英语翻译");
url.searchParams.set("roles", "你是专业翻译，可精准翻译中英文内容");
url.searchParams.set("imag", "https://example.com/avatar/translator.png");
url.searchParams.set("sex", 2);
url.searchParams.set("type", 1);
url.searchParams.set("user", "user_account");
url.searchParams.set("pass", "user_password");

fetch(url.toString())
.then(res => res.json())
.then(res => {
  console.log(res.code === 200 ? "添加成功" : "添加失败：" + res.msg);
});

Python（令牌启用，token验证）

import requests

# 令牌启用时添加AI角色
params = {
    "appid": "your_app_id",
    "name": "历史顾问",
    "roles": "精通中外历史，能详细解答历史事件和人物相关问题",
    "imag": "https://example.com/avatar/history_consultant.png",
    "sex": 0,
    "type": 2,
    "token": "valid_user_token"
}

response = requests.post(
    "https://nobase.cn/api/ai/role_add",
    data=params,
    timeout=15
)
res_data = response.json()
print(res_data["msg"] if res_data["code"] == 200 else f"错误：{res_data['msg']}")

Python（令牌未启用，user+pass验证）

import requests

# 令牌未启用时添加AI角色
params = {
    "appid": "your_app_id",
    "name": "生活助手",
    "roles": "提供日常生活建议，包括饮食、出行等方面",
    "imag": "https://example.com/avatar/life_helper.png",
    "sex": 1,
    "type": 1,
    "user": "user_account",
    "pass": "user_password"
}

response = requests.get(
    "https://nobase.cn/api/ai/role_add",
    params=params,
    timeout=15
)
print(response.json())

核心逻辑说明

1. 验证模式

模式	验证流程	关键限制
令牌启用（应用配置）	1. 校验appid、name、roles、imag、sex、type、token必选参数； 2. 系统通过appid自动关联开发者信息； 3. 验证token有效性并获取用户信息； 4. 校验开发者、应用及用户数据关联性。	token无效/过期返回401；参数缺失返回204；appid无效返回204。
令牌未启用（应用配置）	1. 校验appid、name、roles、imag、sex、type、user、pass必选参数； 2. 系统通过appid自动关联开发者信息； 3. 验证user+pass正确性； 4. 校验开发者、应用及用户数据关联性。	账号密码错误返回407；参数缺失返回204；appid无效返回204。

2. 状态校验规则

• 基础存在性校验：开发者账号、应用、应用配置、用户账户必须存在，否则返回对应“未注册/不存在”提示；
• 账号状态：开发者账号需为“正常”状态，否则返回“开发者账号状态异常”；
• 应用状态：应用不可处于“停用”或“审核中”状态，否则返回“应用已停用”或“应用审核中”；
• VIP状态：开发者VIP需在有效期内（未逾期），否则返回含逾期时长的提示（如“已逾期(30天)”）；
• 用户会员状态：若用户为VIP角色用户，会员需在有效期内，否则返回“账号会员已过期，请续费”。

3. 业务处理流程

1. 参数关联：通过appid查询并关联开发者信息，确保应用与开发者绑定关系正确；
2. 身份验证：根据应用配置的验证方式（token或user+pass）验证用户身份有效性；
3. 状态校验：依次校验开发者账号、应用、用户的状态及VIP权限；
4. 角色添加：校验通过后，将角色信息（名称、描述、头像、性别、类型等）插入角色数据库；
5. 结果返回：返回添加成功提示或失败原因。

注意事项

1. 参数规范

   • 所有必选参数不可为空，name建议控制在1-20字符，roles建议控制在10-500字符；
   • imag需为有效的图片URL（支持http/https协议），否则可能导致前端展示异常；
   • sex和type为数字类型，需符合开发者中心定义的类型规范（如sex仅支持0/1/2）。

2. 安全建议

   • 令牌未启用时，pass以加密方式传输，生产环境必须使用HTTPS协议；
   • 角色添加权限通常授予管理员用户，需做好用户权限分级控制；
   • appid为核心标识，需避免泄露给未授权第三方。

3. 权限限制

   • 仅VIP开发者账号可添加角色，非VIP或逾期账号会被拒绝；
   • 应用处于“审核中”或“停用”状态时，无法添加新角色；
   • 不同类型的角色可能受应用配置限制（如专业型角色需额外权限）。

4. 扩展说明

   • 角色添加后可通过“角色管理接口”进行编辑或删除；
   • 角色的type字段用于前端分类展示，建议在开发者中心统一规划类型标识；
   • 角色头像URL建议使用稳定的存储服务（如对象存储），避免失效。