Bot 接入

在 Bot 或第三方服务中调用平台 HTTP API 的基本方法。

接入流程

注册平台账号
登录开发者控制台并直接生成 API Key
在 Bot 代码中携带 Authorization: Bearer <aw_xxx> 调用接口
处理返回数据

鉴权方式

受保护的 /api/v1/* 与 /v2/* 接口均通过 API Key 鉴权。在请求头中携带 Authorization，不要使用 X-API-Key。API 基址固定为 https://api.emptysekai.com；游戏数据能力目前仅支持国服。控制台只保留当前一把 Key；轮换是原子替换，旧 Key 会立即失效且无法恢复。

API 基址	https://api.emptysekai.com
支持区服	仅国服（CN）
鉴权方式	Authorization: Bearer <aw_xxx>
数据格式	JSON（请求与响应均 UTF-8）
HTTP 方法	GET / POST

Bot 用户的绑定流程

Bot 用户要使用名片 / 组卡等功能，必须先将自己的 QQ 号与游戏账号绑定。绑定的本质是声明"这个 QQ 号对应这个游戏内ID"，平台侧会校验游戏账号真实存在。

① Bot 收集用户信息

用户在 bot 中提供 QQ 号和游戏内 ID（game_user_id）。

② Bot 调用 bind/numeric 创建绑定

bash

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qq_user_id": "123456", "game_user_id": "7xxxxxxxx"}' \
  "https://api.emptysekai.com/api/v1/bind/numeric"

平台会调 scapus 验证账号是否真实存在，存在则创建 binding。

③ 绑定后可用 qq_user_id 查询

所有支持 game_user_id 的端点（profile/deck 等）都接受 qq_user_id 参数，平台自动解析为游戏内 ID。

④ 管理绑定

用 list 查看、set-alias 起别名、set-default 设默认、remove 删除。

限速

每个应用有每分钟请求上限（默认 120 RPM）。超限会返回 429 并附 Retry-After。响应头包含：

X-RateLimit-Limit: 本窗口上限
X-RateLimit-Remaining: 本窗口剩余额度
X-RateLimit-Reset: 窗口重置的 UNIX 时间戳

常用接口示例

用户名片

查询指定国服玩家的名片媒体；游戏 ID 只放在 URL 路径中。该端点当前临时免 API Key，示例保留 Header 以兼容后续恢复鉴权。

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.emptysekai.com/v2/profiles/7xxxxxxxx/media"

组卡推荐

提交组卡条件，返回推荐编队 JSON。

bash

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": 123, "song_difficulty": "master"}' \
  "https://api.emptysekai.com/api/v1/deck/recommend"

错误处理

错误码	HTTP 状态	处理方式
UNAUTHORIZED	401	检查 API Key 是否携带正确、是否仍有效
FORBIDDEN	403	应用缺少所需 scope，联系管理员授予
RATE_LIMITED	429	降低频率，参考 Retry-After 退避重试
INVALID_REQUEST	400	请求参数错误，检查 query/body 字段
INTERNAL_ERROR	500	服务端异常，稍后重试

Bot 接入

在 Bot 或第三方服务中调用平台 HTTP API 的基本方法。

接入流程

注册平台账号
登录开发者控制台并直接生成 API Key
在 Bot 代码中携带 Authorization: Bearer <aw_xxx> 调用接口
处理返回数据

鉴权方式

API 基址	https://api.emptysekai.com
支持区服	仅国服（CN）
鉴权方式	Authorization: Bearer <aw_xxx>
数据格式	JSON（请求与响应均 UTF-8）
HTTP 方法	GET / POST

Bot 用户的绑定流程

① Bot 收集用户信息

用户在 bot 中提供 QQ 号和游戏内 ID（game_user_id）。

② Bot 调用 bind/numeric 创建绑定

bash

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qq_user_id": "123456", "game_user_id": "7xxxxxxxx"}' \
  "https://api.emptysekai.com/api/v1/bind/numeric"

平台会调 scapus 验证账号是否真实存在，存在则创建 binding。

③ 绑定后可用 qq_user_id 查询

所有支持 game_user_id 的端点（profile/deck 等）都接受 qq_user_id 参数，平台自动解析为游戏内 ID。

④ 管理绑定

用 list 查看、set-alias 起别名、set-default 设默认、remove 删除。

限速

每个应用有每分钟请求上限（默认 120 RPM）。超限会返回 429 并附 Retry-After。响应头包含：

X-RateLimit-Limit: 本窗口上限
X-RateLimit-Remaining: 本窗口剩余额度
X-RateLimit-Reset: 窗口重置的 UNIX 时间戳

常用接口示例

用户名片

查询指定国服玩家的名片媒体；游戏 ID 只放在 URL 路径中。该端点当前临时免 API Key，示例保留 Header 以兼容后续恢复鉴权。

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.emptysekai.com/v2/profiles/7xxxxxxxx/media"

组卡推荐

提交组卡条件，返回推荐编队 JSON。

bash

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": 123, "song_difficulty": "master"}' \
  "https://api.emptysekai.com/api/v1/deck/recommend"

错误处理

错误码	HTTP 状态	处理方式
UNAUTHORIZED	401	检查 API Key 是否携带正确、是否仍有效
FORBIDDEN	403	应用缺少所需 scope，联系管理员授予
RATE_LIMITED	429	降低频率，参考 Retry-After 退避重试
INVALID_REQUEST	400	请求参数错误，检查 query/body 字段
INTERNAL_ERROR	500	服务端异常，稍后重试