API 参考
API 基址是 https://api.emptysekai.com（不是 auth.emptysekai.com，也不包含 /api/v1）。受保护的请求需在 Header 中携带 Authorization: Bearer <aw_xxx>，且 API Key 需具备对应 scope。游戏数据能力目前仅支持国服。
名片
scope: profile仅支持《世界计划：缤纷舞台 feat. 初音未来》国服。API 基址固定为 https://api.emptysekai.com；玩家 ID 只放在 URL 路径中，不接受 query 或请求体中的 ID。该端点当前临时免 API Key，服务端保留独立开关以便恢复鉴权。
/v2/profiles/{gameUserId}/media唯一的公开名片媒体端点。逐页只返回 image/video 类型、CDN URL、字节数、缓存状态和精简的绘制/编码/生成/上传/签名耗时；静态页为 JPEG，动态页为 MP4。外层 timing 与 Bot 同口径：total_ms 是请求进入 Scapus 到全部媒体上传完成的墙钟时间，compute_ms 是所有成功页总渲染+编码，queue_wait_ms 仅是 Web 因 429 实际退避等待。生成槽繁忙时由 Web 保持连接重试，最长 60 秒。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| gameUserId | string | 必填 | 5-20 位数字游戏用户 ID（路径参数）。 |
| page | integer | 可选 | 只返回指定的 1-based 名片页。 |
/api/v1/personal-profile个人主页数据（含多页名片、自定义内容）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| game_user_id | string | 必填 | 游戏内用户 ID。 |
组卡
scope: deck返回渲染后的卡组图片 URL 列表。需要用户上下文（qq_user_id 或 game_user_id）且用户必须在 scapus 中存在。
/api/v1/deck/recommend按条件推荐最优组卡。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | game_user_id | string | 必填 | 用户标识，二选一必填。 |
| event_id | string | 可选 | 活动 ID。默认: 当前活动。 |
| target | string | 可选 | 优化目标：score（分数）/ power（综合力）/ mysekai（烤森）。默认: score。 |
| live_type | string | 可选 | Live 类型：challenge 等。默认: 无。 |
| boost | number | 可选 | 火数加成（1-10），仅影响最终点数计算。默认: 1。 |
| max_profile | boolean | 可选 | 使用顶配模拟（满图鉴满配账号）。默认: false。 |
| card_config_override | object | 可选 | 养成覆盖：level_max / master_max / skill_max / episode_read / canvas，可叠加。默认: 无（使用用户实际）。 |
| fixed_cards | number[] | 可选 | 固定卡牌 ID 列表（强制含）。第一个为队长。默认: []。 |
| fixed_character_names | string[] | 可选 | 固定角色名列表。第一个为队长，Web 侧解析为 ID。默认: []。 |
| music_query | string | 可选 | 歌曲名、简称或别名。Web 侧解析为 music_id；与 music_id 同传时 music_id 优先。 |
| challenge_character | string | 可选 | 挑战角色名或别名。Web 侧解析为 challenge_live_character_id；省略时挑战组卡会跑全角色并返回单张排序图。 |
| world_bloom_character | string | 可选 | WL 章节角色名或别名。Web 侧按角色优先仲裁，解析为 world_bloom_character_id。 |
| music_diff | string | 可选 | 歌曲难度：expert / master / hard / normal / easy / append。默认: expert。 |
| force_no_event | boolean | 可选 | 强制不限定活动（如最强/最弱组卡）。默认: false。 |
| minimize | boolean | 可选 | 反转优化方向（最弱组卡用）。默认: false。 |
⚠ qq_user_id 查询需先 numeric 绑定。
参数组合与冲突规则
# 常用组合（对应 umbel Bot 命令） 活动组卡: event_id=xxx, target=score 最强组卡: force_no_event=true, target=power 最弱组卡: force_no_event=true, target=power, minimize=true 烤森组卡: live_type=mysekai, target=mysekai 挑战组卡: live_type=challenge # 参数约束 fixed_cards 与 fixed_character_names 可同时指定，但合计不能超过 5 个槽位 live_type=challenge 不支持 fixed_character_names（只能用 fixed_cards 的 #卡ID） live_type=challenge 省略 challenge_character 时表示全角色挑战组卡 force_no_event=true 时 event_id 被忽略 # 语义说明 boost 仅影响最终点数计算，不改推荐卡组 card_config_override 各子项可叠加（如同时设 level_max=true, skill_max=true） music_query 由 web 本地 alias 索引解析，scapus 只接收 music_id 角色别名由 web 的 character_nicknames 映射解析，浏览器 /deck 页会先解析成数字 ID 再交给本地 WASM music_diff 不指定时默认 expert
/api/v1/music/resolve公开歌曲别名解析。浏览器组卡页会调用该端点把歌曲输入预解析为 music_id。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| query | string | 必填 | 歌曲 ID、标题或别名。 |
| region | string | 可选 | 区服，默认 cn。 |
/api/v1/character/resolve公开角色别名解析。浏览器组卡页会调用该端点把角色输入预解析为 character_id。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| query | string | 必填 | 角色 ID、中文名、罗马字或常用缩写。 |
账号绑定
scope: bindingBot 侧以 qq_game_bindings 为权威：/绑定 创建 numeric 声明绑定；/验证 C-xxx 只确认 QQ 所有权；游戏签名验证在 Web /me 完成后，只会同步到当前已确认 QQ。/解绑 调 remove 删除指定绑定。
/api/v1/bind/numeric声明绑定：将 QQ 号与游戏 ID 关联。scapus 会验证账号存在性。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
| game_user_id | string | 必填 | 游戏内 ID（5-20位纯数字）。 |
/api/v1/bind/confirm提交用户在 Web 端完成游戏内签名验证后得到的 C-xxx 确认码。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
| confirm_code | string | 必填 | C-xxx 格式的确认码。 |
/api/v1/bind/accounts查询 QQ 号下已绑定的游戏账号列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。返回含绑定层级、默认账号、别名。 |
/api/v1/bind/list列出 QQ 号下的 numeric 和 verified 两类绑定（旧接口，建议用 accounts）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
/api/v1/bind/set-default切换 QQ 用户的默认游戏账号。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
| game_user_id | string | 必填 | 要设为默认的游戏 ID。 |
/api/v1/bind/set-alias为绑定设置别名。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
| game_user_id | string | 必填 | 游戏 ID。 |
| alias | string | 必填 | 要设置的别名。 |
/api/v1/bind/remove删除绑定。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qq_user_id | string | 必填 | 用户 QQ 号。 |
| game_user_id | string | 必填 | 游戏 ID。 |
| tier | numeric | verified | 必填 | 绑定层级；当前实现按 QQ + 游戏 ID 删除该行，tier 用于调用侧显式确认。 |
上传
scope: upload_suite/api/v1/upload/suite上传卡组/suite 数据。注册时默认授予该 scope。
错误码
| 错误码 | HTTP | 说明 |
|---|---|---|
| OK | 200 | 请求成功 |
| INVALID_REQUEST | 400 | 请求参数错误（字段缺失、类型错误等） |
| UNAUTHORIZED | 401 | 未提供 API Key 或 Key 无效 |
| SCOPE_DENIED | 403 | API Key 缺少所需 scope |
| BINDING_REQUIRED | 403 | 使用 qq_user_id 但未绑定 |
| BINDING_TIER_INSUFFICIENT | 403 | 需要 verified 绑定，仅有 numeric |
| NO_ACTIVE_EVENT | 404 | 省略 event_id 但当前无进行中的活动 |
| NOT_FOUND | 404 | 资源（账号、绑定、活动）不存在 |
| UPSTREAM_ERROR | 502 | 上游 scapus 服务返回错误 |
| RATE_LIMITED | 429 | 请求频率超限，参考响应头 X-RateLimit-* |
| INTERNAL_ERROR | 500 | 服务端异常，稍后重试 |