---
url: https://wiki.awmc.team/dev/chart-preview-api.md
---

# 🎵 谱面评价与分析 API

谱面预览平台的公开 REST API，支持谱面查询、评论、评分、成绩提交与排行榜等功能。

::: tip 平台地址

* **Base URL**: `https://v.wmc.pub/api/v1/`
* **源码仓库**: [Pimeng/Maimai-Chart-Preview](https://github.com/Pimeng/Maimai-Chart-Preview)
  :::

::: warning 🔐 鉴权方式
业务请求须在请求头携带：

`Authorization: Bearer <api-key>`

获取方式：登录 https://v.wmc.pub → 顶部导航栏钥匙图标 → `/api-keys` 页面 → 新建 API Key。
:::

::: danger ⚠️ 注意
API Key **仅在创建时显示一次**，丢失需重新创建。
:::

***

## 获取 API Key

1. 登录网站 (https://v.wmc.pub)
2. 点击顶部导航栏钥匙图标，进入 `/api-keys` 页面
3. 点击「新建」，输入名称，创建后复制保存

***

## 接口列表

### 1. 谱面接口

#### 1.1 获取谱面列表

***

#### 1.2 获取谱面详情

**:chartKey 格式**: `{songId}:{kind}:{difficulty}`，例如 `123:dx:4`

***

#### 1.3 获取谱面标签摘要

**字段说明**:

| 字段 | 类型 | 说明 |
|------|------|------|
| 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 获取谱面评论

***

### 3. 评分接口

#### 3.1 获取评分统计

***

### 4. 成绩接口

#### 4.1 获取成绩提交

***

### 5. 排行榜接口

#### 5.1 获取排行榜

***

### 6. 统计接口

#### 6.1 获取全局统计

***

### 7. API Key 管理接口

::: warning 🔐 需登录
以下接口需要通过网页登录后调用（浏览器 Session 或 JWT）。
:::

#### 7.1 创建 API Key

#### 7.2 列出我的 API Key

#### 7.3 删除 API Key

***

### 8. 管理员接口

::: danger 🔒 需管理员权限
以下接口仅限管理员调用。
:::

#### 8.1 获取 API 使用统计

#### 8.2 获取调用趋势

***

## 错误响应

所有接口在出错时返回统一格式：

```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"
```
