栖云居
主页 玩家查询 聊天室 更新日志 用户中心 维基 · API

维基 · API

玩家数据查询、等级与栖云币、玩法统计、用户中心聊天等接口文档

玩家信息查询
API 基础信息
项目说明
服务地址http://服务器IP:19898
返回格式JSON（UTF-8），均带 ok 字段
写入鉴权仅管理 API Key（管理员后台获取，/qadmin 授权或主 api_key）
限速查询接口同一 IP 每 5 秒 1 次（玩法查询 2 秒 1 次），聊天发言每 1 秒 1 条
跨域已开启 CORS，可被网页 / 脚本直接调用
参数既支持 QueryString，也支持 POST 表单体（application/x-www-form-urlencoded）。
用户认证

POST/api/register

参数: username  用户名
      password  密码
      card      卡密（可选；仅 API 开发者接入时需要，QK-XXXX-XXXX-XXXX，一次性）

普通玩家注册免费（只需用户名+密码），用于用户中心/聊天室。
返回: { "ok": true, "token": "会话凭证", "admin": false }
错误: 409 用户名已存在 / 403 卡密无效

POST/api/login

参数: username  用户名
      password  密码
普通用户返回会话 token（用于用户中心/聊天室）。
管理员返回: { "ok": true, "api_key": "...", "admin": true }
普通用户返回: { "ok": true, "token": "...", "admin": false }
错误: 401 登录失败

POST/api/reset

参数: api_key  管理员 Key
仅管理员可用；重置管理员用户的 Key。
返回: { "ok": true, "api_key": "新Key" }（旧 Key 立即失效）

GET/api/me?token=xxx 或 /api/me?api_key=xxx

普通用户: { "ok": true, "username": "...", "token": "...", "admin": false }
管理员:   { "ok": true, "username": "...", "api_key": "...", "admin": true }
等级 / 栖云币

GET/qyx/find/api?name=玩家

返回: { "player":"...", "level":10, "total_exp":1234, "current_exp":234, "next_level_exp":500, "coins":100 }
错误: 404 玩家不存在 / 429 频率限制

POST/gyx/set/api

参数: api_key       管理 Key（管理员）
      name          玩家名
      以下三选一:
      total_exp=值   直接设置总经验
      add_exp=值     增加经验（可为负数）
      set_coins=值   设置栖云币
      add_coins=值   增加栖云币（可为负数）

返回: { "ok": true, "action": "add_exp", "player": "...", "added": 100, "new_total": 1334, "level": 10, "upgraded": true }
玩法统计 API
每个玩法都有独立的接口，玩法英文名可在下方“玩法列表”中查看（由管理后台动态维护）。kd 由 kills / deaths 自动计算，无需手动写入。

POST/gyx/set/api/{game}/set

参数: api_key   管理 Key（管理员）
      player    玩家名
      任意字段   = 数值（只写想覆盖的字段即可，例如 kills=10 deaths=2）

示例: POST /gyx/set/api/bedwars/set
      api_key=xxx&player=Steve&kills=10&deaths=2&beds_broken=3

POST/gyx/set/api/{game}/add

参数: 同上，但字段为增量（可负数）。
示例: POST /gyx/set/api/thepit/add
      api_key=xxx&player=Steve&kills=1&gold=50&streak=1

GET/gyx/set/api/{game}/find?player=玩家

或   /gyx/set/api/{game}/find/玩家
返回: { "ok": true, "game": "bedwars", "player": "Steve", "stats": { "wins":5, "kills":10, "kd":5 } }
玩法列表 由管理后台动态维护
玩法名（game）中文名可用字段
加载中...
更新日志 / 公告（公开只读）

GET/api/changelog

返回: { "ok": true, "items": [ { "id":1, "title":"v1.2 · 更新内容", "content":"...", "date":"2026-08-01 12:00:00" } ] }

GET/api/announcements

返回: { "ok": true, "items": [ { "id":1, "title":"...", "content":"...", "date":"..." } ] }
（新增 / 删除需管理员权限，在管理后台操作）
用户中心聊天（实时转发）

POST/api/chat/send

参数: token      普通用户会话凭证（或管理员 api_key）
      type      text / image / voice
      data      文本内容，或图片 / 语音的 dataURL（上限 700KB）
返回: { "ok": true, "seq": 123 }

GET/api/chat/poll?since=seq

长轮询（最长 20 秒），返回 seq 之后的新消息。
返回: { "ok": true, "seq": 124, "messages": [ { "seq":123, "user":"...", "type":"text", "data":"...", "ts": 1760000000000 } ] }

GET/api/chat/history?since=seq

立即返回当前服务器内存中的最新消息（最多 100 条 / 24MB）。
服务器只做临时转发，完整历史请保存在浏览器 localStorage。
玩家全信息查询（推荐）

GET/api/player/find?name=玩家

一次性返回玩家等级 / 经验 / 栖云币 + 全部玩法统计：
返回: {
  "ok": true, "player": "Steve",
  "level": 10, "total_exp": 1234, "current_exp": 234, "next_level_exp": 500, "coins": 100,
  "stats": { "bedwars": { "kills": 10, "deaths": 2, "kd": 5 }, "skywars": { ... } }
}
错误: 404 玩家不存在
管理接口（管理员专用）
以下接口需要管理员 Key（/qadmin 授权或主 api_key）。页面形式的管理功能见 管理后台。
POST /api/changelog/add?api_key=xxx    body: version,title,content
POST /api/changelog/delete?api_key=xxx body: id
POST /api/announcements/add?api_key=xxx    body: title,content
POST /api/announcements/delete?api_key=xxx body: id
POST /api/admin/apis/create?api_key=xxx    body: game,name_cn,fields(逗号分隔)
POST /api/admin/apis/delete?api_key=xxx    body: game
GET  /api/apis                                    (公开，列出全部玩法)
GET  /api/admin/users?api_key=xxx
POST /api/admin/users/grant?api_key=xxx    body: username,admin=1/0
游戏内管理员授权：/qadmin set 用户名 / /qadmin list。
栖云居 · QiyunJu —— 维基与 API 文档