AI角色列表查询接口

用于分页查询指定应用下的启用状态AI角色列表，支持动态身份验证（令牌启用时通过token验证，令牌未启用时通过user+pass验证），自动关联开发者信息，包含状态及VIP权限校验机制。

请求地址 GET / POST

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

请求参数

参数名	位置	类型	必选	说明
appid	query	string	✅ 是	应用唯一标识，从开发者中心获取
page	query	number	✅ 是	页码，分页查询的起始页（如1表示第一页）
limit	query	number	✅ 是	每页条数，分页查询的每页数据量（如10表示每页10条）
token	query	string	条件必选	用户令牌，仅令牌启用（应用配置为token验证）时需传递
user	query	string	条件必选	用户账号，仅令牌未启用（应用配置为账号密码验证）时需传递
pass	query	string	条件必选	用户密码，仅令牌未启用（应用配置为账号密码验证）时需传递

返回示例

成功响应（查询到角色数据）

{
  "code": 200,
  "count": 25,
  "data": [
    {
      "ID": 1,
      "name": "数学导师",
      "roles": "专业数学辅导，擅长中小学知识点讲解与习题解析",
      "img": "https://example.com/avatar/math_teacher.png",
      "vip": 0,
      "sex": 1,
      "type": 2
    },
    {
      "ID": 2,
      "name": "英语翻译",
      "roles": "精准中英文互译，支持专业领域术语翻译",
      "img": "https://example.com/avatar/translator.png",
      "vip": 1,
      "sex": 2,
      "type": 1
    }
  ]
}

失败响应（参数问题）

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

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

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

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

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

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

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

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

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

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

失败响应（无数据）

{
  "code": 401,
  "msg": "暂无角色数据"
}

返回数据结构

参数名	类型	说明
code	number	状态码：200=查询成功；204=参数缺失/错误；401=无角色数据/token无效；404=开发者/应用状态异常/账号未注册/应用不存在；407=应用配置不存在
count	number	总数据量：仅成功响应时返回，标识符合条件的角色总数
data	array	角色列表：仅成功响应时返回，包含当前页的角色数据对象数组
msg	string	响应信息：失败时返回错误原因说明

代码示例

JavaScript（令牌启用，token验证）

// 令牌启用时查询角色列表
const params = new URLSearchParams({
  appid: "your_app_id",
  page: 1,
  limit: 10,
  token: "valid_user_token"
});

fetch("https://nobase.cn/api/ai/role_list", {
  method: "POST",
  body: params,
  headers: { "Content-Type": "application/x-www-form-urlencoded" }
})
.then(res => res.json())
.then(res => {
  if (res.code === 200) {
    console.log("总角色数：", res.count);
    console.log("当前页角色：", res.data);
  } else {
    console.error("查询失败：", res.msg);
  }
});

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

// 令牌未启用时查询角色列表
const url = new URL("https://nobase.cn/api/ai/role_list");
url.searchParams.set("appid", "your_app_id");
url.searchParams.set("page", 2);
url.searchParams.set("limit", 5);
url.searchParams.set("user", "user_account");
url.searchParams.set("pass", "user_password");

fetch(url.toString())
.then(res => res.json())
.then(res => {
  if (res.code === 200) {
    console.log("角色列表：", res.data);
  } else {
    console.error("错误：", res.msg);
  }
});

Python（令牌启用，token验证）

import requests

# 令牌启用时查询角色列表
params = {
    "appid": "your_app_id",
    "page": 1,
    "limit": 8,
    "token": "valid_user_token"
}

response = requests.post(
    "https://nobase.cn/api/ai/role_list",
    data=params,
    timeout=15
)
res_data = response.json()
if res_data["code"] == 200:
    print(f"共{res_data['count']}个角色")
    for role in res_data["data"]:
        print(f"角色：{role['name']}，ID：{role['ID']}")
else:
    print(f"查询失败：{res_data['msg']}")

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

import requests

# 令牌未启用时查询角色列表
params = {
    "appid": "your_app_id",
    "page": 1,
    "limit": 10,
    "user": "user_account",
    "pass": "user_password"
}

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

核心逻辑说明

1. 验证模式

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

2. 状态校验规则

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

3. 业务处理流程

1. 参数关联：通过appid查询并关联开发者信息，确保应用与开发者绑定关系正确；
2. 身份验证：根据应用配置的验证方式（token或user+pass）验证用户身份有效性；
3. 状态校验：依次校验开发者账号、应用的状态及VIP权限；
4. 分页计算：根据page和limit计算起始位置（startCount = (page - 1) * limit），确定查询范围；
5. 数据查询：查询指定应用下启用状态（show=1）的角色数据，按ID升序排序；
6. 结果返回：返回角色列表、总条数（count），或无数据提示。

注意事项

1. 参数规范

   • page和limit需为正整数（page ≥ 1，limit ≥ 1），否则可能导致分页计算错误；
   • 建议limit取值范围为1-50，过大可能影响接口响应速度；
   • 仅返回启用状态的角色（show=1），禁用状态的角色不会出现在列表中。

2. 安全建议

   • 令牌未启用时，pass需通过HTTPS加密传输，避免明文泄露；
   • 分页查询接口建议添加频率限制，防止恶意请求；
   • appid需严格保密，避免未授权用户查询角色数据。

3. 权限限制

   • 仅开发者账号对应的应用角色可被查询，跨应用查询会被拒绝；
   • 非VIP或VIP逾期的开发者账号无法查询角色列表；
   • 应用处于“审核中”或“停用”状态时，禁止查询角色列表。

4. 扩展说明

   • 角色数据中的vip字段标识是否为VIP专属角色（0=普通，1=VIP）；
   • type字段用于角色分类（如1=通用型，2=专业型），具体含义由应用配置定义；
   • 如需查询所有角色（含禁用状态），可使用“角色管理接口”（需管理员权限）。