🎵 谱面评价与分析 API
谱面预览平台的公开 REST API，支持谱面查询、评论、评分、成绩提交与排行榜等功能。
平台地址
- Base URL:
https://v.wmc.pub/api/v1/ - 源码仓库: Pimeng/Maimai-Chart-Preview
🔐 鉴权方式
业务请求须在请求头携带：
Authorization: Bearer <api-key>
获取方式：登录 https://v.wmc.pub → 顶部导航栏钥匙图标 → /api-keys 页面 → 新建 API Key。
⚠️ 注意
API Key 仅在创建时显示一次，丢失需重新创建。
获取 API Key
- 登录网站 (https://v.wmc.pub)
- 点击顶部导航栏钥匙图标，进入
/api-keys页面 - 点击「新建」，输入名称，创建后复制保存
接口列表
1. 谱面接口
1.1 获取谱面列表
GET获取谱面列表
/api/v1/charts▼
1.2 获取谱面详情
:chartKey 格式: {songId}:{kind}:{difficulty}，例如 123:dx:4
GET获取谱面详情
/api/v1/charts/:chartKey▼
1.3 获取谱面标签摘要
GET获取谱面标签摘要
/api/v1/charts/:chartKey/tags▼
字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| tags.difficultyClassification | object | 难度分类：tag=normal/water/fake，label=正常谱/水/虚高谱 |
| tags.difficultyClassification.estimatedLevel | float | 回归模型预测的难度值 |
| tags.difficultyClassification.deviation | float | 预测值与官标的偏差（正=虚高，负=偏低） |
| tags.radarTags | array | 雷达轴高分项，score 0-100 |
| tags.evaluationTags | array | 评估轴高分项（体力谱/底力谱/星星谱/键盘谱/高物量） |
| tags.features | array | 回归模型贡献最大的特征，direction=up/down 表示提升/降低难度 |
| tags.features.contribution | float | 该特征对难度值的贡献量（正=加难度，负=减难度） |
| tags.patterns | array | 检测到的谱面模式，severity=high/mid/low |
| tags.patterns.count | int | 该模式出现次数 |
| tags.patterns.severity | string | high=高强度（strength≥5），mid=中等，low=低 |
radarTags 可能的 label：交互、散打、扫键、绝赞段、转圈、大位移、定拍、拆弹、爆发、纵连、跳拍、错位、一笔画、反手
evaluationTags 可能的 label：体力谱、底力谱、星星谱、键盘谱、高物量
features 可能的 label：平均密度、高密度惩罚、峰值密度、滑条占比、触摸占比、交叉手、同位连打、跳拍节奏、一笔画、偏移、爆发段、转圈、横扫
patterns 可能的 label：错位星星、交互、纵连、跳拍、一笔画、反手/大位移同押、定拍、绝赞段、爆发、扫键、转圈、触摸拆分、散打、拆弹
2. 评论接口
2.1 获取谱面评论
GET获取谱面评论
/api/v1/charts/:chartKey/comments▼
3. 评分接口
3.1 获取评分统计
GET获取评分统计
/api/v1/charts/:chartKey/ratings▼
4. 成绩接口
4.1 获取成绩提交
GET获取成绩提交
/api/v1/charts/:chartKey/scores▼
5. 排行榜接口
5.1 获取排行榜
GET获取排行榜
/api/v1/rankings▼
6. 统计接口
6.1 获取全局统计
GET获取全局统计
/api/v1/stats▼
7. API Key 管理接口
🔐 需登录
以下接口需要通过网页登录后调用（浏览器 Session 或 JWT）。
7.1 创建 API Key
POST创建 API Key
/api/v1/api-keys▼
7.2 列出我的 API Key
GET列出我的 API Key
/api/v1/api-keys▼
7.3 删除 API Key
DELETE删除 API Key
/api/v1/api-keys/:id▼
8. 管理员接口
🔒 需管理员权限
以下接口仅限管理员调用。
8.1 获取 API 使用统计
GET获取 API 使用统计
/api/v1/admin/api-usage▼
8.2 获取调用趋势
GET获取调用趋势
/api/v1/admin/api-usage/trends▼
错误响应
所有接口在出错时返回统一格式：
json
{
"message": "错误信息"
}| 状态码 | 说明 |
|---|---|
| 401 | 未认证或 API Key 无效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
快速开始
bash
# 1. 获取谱面列表
curl -H "Authorization: Bearer mk_live_xxx" \
https://v.wmc.pub/api/v1/charts
# 2. 获取谱面详情
curl -H "Authorization: Bearer mk_live_xxx" \
https://v.wmc.pub/api/v1/charts/123:dx:4
# 3. 获取谱面标签（Bot 用）
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/417:standard:5/tags"
# 4. 自定义阈值（仅显示高分项）
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/417:standard:5/tags?radar_threshold=60&feature_threshold=1.0"
# 5. 获取评论
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/123:dx:4/comments"
# 6. 获取排行榜
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/rankings?sort=rating&limit=10"