服务器地址：http://156.224.28.104
数据格式：请求和响应均为 application/json; charset=utf-8

1. 鉴权（两种密钥）

所有接口都要带请求头：

X-Token: 你的密钥

密钥类型	谁用	权限
管理员主令牌	运营者本人	看全部人的会话、创建/停用用户、改系统设置
用户密钥 uk_ 开头	每个使用者 / 每台脚本	只能操作自己密钥下的会话，互相完全隔离

用户密钥由管理员在网页「用户」菜单里创建，形如 uk_a1b2c3...。
密钥错误或缺失返回 401 {"error":"访问令牌无效"}；访问别人的会话返回 404（不暴露会话是否存在）。

2. 核心接口：一步对话 POST /api/chat

脚本端只接这一个接口就够用：角色设置 + 说的话一起传，服务器自动建角色、存记忆，下次只传会话 ID 和新消息即可续聊。

请求参数（JSON Body）

字段	类型	必填	说明
text	string	是	这一轮说的话
session_id	string	否	会话ID，建议用客户编号，如 kehu-001。不传则服务器自动生成
profile	object	二选一	自定义角色（见第 4 节字段表），首次建会话时传
role_key	string	二选一	服务器预设角色编号 "1"~"10"，用 GET /api/roles 查列表

• 首次对话：text + session_id + profile（或 role_key）
• 后续对话：只传 text + 同一个 session_id，角色和全部历史都在服务器
• 续聊时也可以再次带 profile，只更新人设、不清空聊天记录
• 会话 ID 只允许中文、字母、数字、下划线、短横等文件名字符（\ / : * ? " < > | 会被剔除）

响应

{
  "ok": true,
  "session_id": "kehu-001",
  "is_new": true,
  "reply": "在呢，怎么啦",
  "usage": {
    "elapsed": 1.8,
    "prompt_tokens": 2401,
    "completion_tokens": 12,
    "total_tokens": 2413,
    "cost": 0.0048
  }
}

cost 为按管理员设定单价计算的费用估算（元）。AI 服务异常返回 500 {"error":"AI接口调用失败：..."}。

调用示例

Python（推荐，完整示例见《客户端脚本示例.py》）

import requests
H = {"X-Token": "uk_你的密钥", "Content-Type": "application/json"}

# 第一次：角色 + 话
r = requests.post("http://156.224.28.104/api/chat", headers=H, timeout=120, json={
    "session_id": "kehu-001",
    "profile": {"name": "小甜", "job": "奶茶店店员", "age": "23",
                "persona_desc": "活泼爱撒娇的女生"},
    "text": "在吗"
}).json()
sid = r["session_id"]
print(r["reply"])

# 之后：只传 ID + 话
r = requests.post("http://156.224.28.104/api/chat", headers=H, timeout=120,
                  json={"session_id": sid, "text": "今天累不累"}).json()
print(r["reply"])

curl

curl -X POST http://156.224.28.104/api/chat \
  -H "X-Token: uk_你的密钥" -H "Content-Type: application/json" \
  -d '{"session_id":"kehu-001","role_key":"1","text":"在吗"}'

易语言 / 按键精灵 / 其他语言：向 http://156.224.28.104/api/chat 发 POST，请求头加 X-Token，请求体按上面 JSON 拼接，UTF-8 编码，解析返回 JSON 的 reply 字段即可。接口已开启 CORS，浏览器里的 JavaScript（fetch）也能直接跨域调用。

3. 会话管理接口

方法	路径	说明
GET	/api/me	查询当前密钥身份（管理员/用户名）
GET	/api/roles	预设角色列表（key / 名称 / 完整档案）
GET	/api/sessions	会话列表（用户密钥只返回自己的；管理员返回全部并带 owner_name 归属）
GET	/api/sessions/{sid}	会话详情，含 profile 与 chat_list 完整记录
POST	/api/sessions	仅创建/更新角色不对话（参数同 /api/chat 的角色部分，可带 overwrite:true）
POST	/api/sessions/{sid}/clear	清空聊天记录（保留人设）
DELETE	/api/sessions/{sid}	删除整个会话

GET /api/sessions 返回：

{"sessions": [{"session_id": "kehu-001", "label": "小甜",
               "create_time": "2026-10-03 16:00:00", "msg_count": 12}]}

GET /api/sessions/{sid} 的 chat_list 中，第一条 role:"system" 是人设提示词，之后是 user / assistant 交替，每条含 content 和 time。

4. 自定义角色 profile 字段

全部字段都可选，只填需要的，其余自动补默认值：

字段	含义	字段	含义
name	姓名	marital_status	婚姻状况
nickname	昵称	love_history	感情经历
gender	性别	character	性格
age	年龄	appearance	外貌
hometown	籍贯	height / weight	身高 / 体重
birthplace	出生地	hobby	爱好
location	现居地	favorite_food	爱吃的
nationality	国籍	hate_food	忌口
ethnicity	民族	father / mother	父母职业
job	职业	income	月薪
company	公司	work_time	工作时间
work_year	工作年限	education	学历
major	专业	persona_desc	人设描述（说话方式/性格，最重要）

最简角色只需：{"name": "小甜", "persona_desc": "活泼爱撒娇"}。

拼音/简写参数（脚本端可直接传）

profile 里除了上表的英文标准字段，也支持下面这些拼音/简写名，服务器自动转换；两套名字都传时以标准英文名为准：

脚本传参	等价字段	含义
work	job	职业
lianai	love_history	感情经历
aihao	hobby	爱好
xingge	character	性格
xiaomao	appearance	外貌
shengao / tizhong	height / weight	身高 / 体重
laojia	hometown	籍贯
shouru	income	月薪
hunyin	marital_status	婚姻状况
xingbie / nianling	gender / age	性别 / 年龄
renshe	persona_desc	人设描述

示例（与常见脚本变量一一对应）：

{
  "name": "陈明思", "age": "25", "work": "酒店管理", "location": "广西桂林",
  "lianai": "单身", "aihao": "唱歌", "xingge": "温柔", "xiaomao": "可爱",
  "shengao": "165", "tizhong": "48", "laojia": "广西桂林",
  "shouru": "5000", "hunyin": "未婚"
}

5. 管理员接口（仅主令牌可用，普通密钥返回 403）

方法	路径	说明
GET	/api/users	用户列表（含密钥、会话数、状态）
POST	/api/users	创建用户，body：{"name":"备注名"}，返回一次性展示的 key
POST	/api/users/{uid}/reset-key	重置密钥（旧密钥立即作废）
POST	/api/users/{uid}/status	启用/停用，body：{"status":0} 或 {"status":1}
DELETE	/api/users/{uid}	删除用户（密钥作废，历史会话保留在服务器）
GET / POST	/api/config	查看/修改 API Key、模型、单价、历史条数等系统参数

这些操作也都能在网页端用鼠标完成，不必直接调接口。

6. 错误码与建议

HTTP	含义	处理建议
401	密钥错误/被停用	检查 X-Token；被重置或停用后联系管理员
403	普通密钥调了管理员接口	用主令牌
404	会话不存在 / 不是你的会话	首次对话记得带 profile 或 role_key
400	参数问题（如没传角色、消息为空）	看返回的 error
500	AI 上游异常（限流 429、超时、余额不足等）	脚本里建议重试 2~3 次，间隔 2/5/10 秒

• 超时设 120 秒：AI 回复正常 1~20 秒，网络抖动时更久。
• session_id 用业务唯一编号（客户号/订单号），不要用随机值否则无法续聊。
• 高频调用做并发控制和重试，同一密钥的会话互不阻塞，但上游 AI 有总并发限制。
• 每次响应的 usage.cost 可自行记账；服务器侧全部费用明细在 使用日志.txt，按账号、会话逐行记录。