Malody API

连接 Malody 并处理数据的API后端

图片演示

玩家信息看板	谱面成绩面板	玩家趋势分析	玩家最近成绩

功能概览

功能	JSON	图片	说明
全局排行榜	✅	✅	支持 MM 值 / EXP 两种排名方式
网页排行榜	✅	✅	备用排行榜数据源
玩家信息看板	✅	✅	核心数据卡片 + Wiki + 最近活动
玩家趋势分析	✅	✅	雷达图 + 模式对比 + 数据表格
谱面成绩排行	✅	✅	Top N 排行卡片列表
谱面成绩面板	✅	✅	M5-M0 评级 + 判定分布 + 六边形封面
玩家最近上榜成绩	✅	✅	最近 15 条动态 + Top30 榜核验（≥3 条才出图）
玩家 / 谱面搜索	✅	—	关键词模糊搜索
玩家活动记录	✅	—	最近游玩记录

关于仓库

快速开始

pip install -r requirements.txt
python run.py

服务启动于 http://localhost:8080，访问 /docs 查看 Swagger 交互式文档。

API 端点

所有端点以 /api 为前缀。图片端点默认输出 JPEG，可通过 fmt=png 切换。

图片临时 URL

以下 以 /image 结尾 的接口均支持：

参数	类型	默认	说明
`is_url`	bool	`false`	为 `true` 时不直接返回图片二进制，而是将图片写入 `static/temp/` 并返回可访问的 URL
`img_url_time`	int	`300`	临时文件保留时间（秒），到期后自动删除；范围 `1`～`604800`（7 天）

生成的 URL 形如：http://{主机}:{端口}/static/{随机文件名}.jpg（扩展名与 fmt 一致）。主机与端口由当前请求的 Host/scheme 决定；若服务在反向代理或公网 IP 与监听地址不一致，请设置环境变量 PUBLIC_BASE_URL（例如 http://203.0.113.1:8080），返回的 url 将使用此前缀。

is_url=true 时的 JSON 响应示例：

{
  "success": true,
  "data": {
    "url": "http://203.0.113.1:8080/static/a1b2c3d4e5f6.jpg",
    "expires_in_seconds": 300,
    "expires_at": "2026-03-25T12:05:00.000000Z"
  },
  "message": "图片临时 URL",
  "timestamp": "2026-03-25T12:00:00.000000"
}

排行榜

端点	说明	主要参数
`GET /api/rankings`	网页排行榜（备用）	`mode` 模式 (0-9)，`limit` 数量 (1-200)
`GET /api/rankings/image`	网页排行榜图片	同上 + `fmt` + `is_url` + `img_url_time`
`GET /api/ranking/global`	全局排行榜	`mode` 模式名/数字，`mm` 0=EXP/1=MM，`limit` (1-100)
`GET /api/ranking/global/image`	全局排行榜图片	同上 + `fmt` + `is_url` + `img_url_time`

玩家

端点	说明	主要参数
`GET /api/player/{identifier}`	玩家完整信息	用户名或 UID
`GET /api/player/{identifier}/image`	玩家信息看板图片	`mode` 留空自动选最高排名，`fmt`，`is_url`，`img_url_time`
`GET /api/player/{identifier}/activity`	最近活动记录	`limit` (1-50)
`GET /api/player/{identifier}/recent-scores`	最近上榜成绩（JSON）	固定读取最近 15 条动态
`GET /api/player/{identifier}/recent-scores/image`	最近上榜成绩图	`fmt`，`is_url`，`img_url_time`；有效条数须 >2（至少 3 条）
`GET /api/player/search/{keyword}`	搜索玩家	`limit` (1-50)

最近上榜成绩：/api/player/activity 最近 15 条 → 解析 Achieved #N / Achieved the top（视为 #1）与 /chart/{cid}；N>30 丢弃；/api/ranking/list 仅看前 30 名，玩家不在榜则丢弃；同谱面只保留较新一条动态。图片需 >2 条有效记录。

玩家趋势分析

端点	说明	主要参数
`GET /api/analytics/player-trends/{identifier}`	各模式数据 (JSON)	`mode` 筛选指定模式
`GET /api/analytics/player-trends/{identifier}/image`	趋势分析图片	`mode`，`fmt`，`is_url`，`img_url_time`

趋势分析图片包含：

能力雷达图 — Rank / Level / Accuracy / Combo / Plays 五维对比
模式对比条形图 — 各模式 6 项指标横向对比
详细数据表格 — 所有模式的完整数值

谱面

端点	说明	主要参数
`GET /api/chart/{cid}`	谱面成绩排行	`limit` (1-100)，cid 支持 `c154498` 或 `154498`
`GET /api/chart/{cid}/image`	谱面排行图片	`limit`，`fmt`，`is_url`，`img_url_time`
`GET /api/chart/{cid}/player/{identifier}`	指定玩家谱面成绩（单条最佳）	—
`GET /api/chart/{cid}/player/{identifier}/image`	成绩面板图片	`fmt`，`is_url`，`img_url_time`
`GET /api/charts/search`	搜索谱面	`word` 关键词，`mode`，`limit`

所有「生成图片」的接口均支持 is_url / img_url_time，详见 图片临时 URL。

成绩面板图片包含：

M5-M0 评级 + Judge 等级 (A-E) + Pro 标识
分数 / 准确率 / Combo 详情
BEST / COOL / GOOD / MISS 判定分布条
六边形封面 + Star Rating + Statistics
玩家全局排名信息

游戏模式

参数	模式	参数	模式
`key` / `0`	Key	`taiko` / `5`	Taiko
`catch` / `3`	Catch	`ring` / `6`	Ring
`pad` / `4`	Pad	`slide` / `7`	Slide
		`live` / `8`	Live
		`cube` / `9`	Cube

mode 参数支持名称（不区分大小写）或数字。留空时自动选择排名最高的模式。

评级系统

等级	条件	等级	条件
M5	全 BEST，准确率 100%	M2	准确率 ≥ 80%
M4	无 MISS，准确率 ≥ 95%	M1	准确率 ≥ 70%
M3	准确率 ≥ 90%	M0	准确率 < 70%

判定等级：A(EASY) → B(EASY+) → C(NORMAL) → D(NORMAL+) → E(HARD)

响应格式

// 成功
{
  "success": true,
  "data": { ... },
  "message": "描述信息",
  "timestamp": "2026-03-25T12:00:00.000000"
}

// 错误
{
  "success": false,
  "error": "错误描述",
  "timestamp": "2026-03-25T12:00:00.000000"
}

项目结构

malody_api/
├── run.py                          # 入口（挂载 /static 临时图片）
├── malody_client.py                # Malody API 客户端
├── requirements.txt
├── routers/
│   └── api.py                      # 全部 API 路由
├── utils/
│   └── temp_image.py               # 临时图片写入与 URL 生成
├── static/
│   └── temp/                       # 临时图片目录（git 忽略内容，保留 .gitkeep）
├── image/
│   ├── renderer.py                 # 渲染工具 (背景/渐变/圆角)
│   ├── colors.py                   # 颜色常量
│   ├── fonts.py                    # 字体加载
│   ├── panels/
│   │   ├── panel_dashboard.py      # 玩家信息看板
│   │   ├── panel_score.py          # 谱面成绩面板
│   │   ├── panel_recent_scores.py      # 玩家最近上榜成绩表
│   │   ├── panel_trends.py         # 趋势分析面板
│   │   └── panel_card_list.py      # 排行榜卡片列表
│   └── components/
│       ├── avatar.py               # 头像组件
│       ├── player_card.py          # 玩家卡片
│       ├── text.py                 # 文字渲染
│       └── banner.py               # 横幅组件
├── assets/
│   ├── fonts/
│   └── images/
└── demo/                           # 演示图片

技术栈

组件	说明
FastAPI + Uvicorn	异步 Web 框架
Pillow	图片生成与渲染
aiohttp / httpx	异步 HTTP 请求
BeautifulSoup4	网页数据解析

鸣谢

yumu-image — 图片面板样式与布局参考
malody_api (ChuanYuanNotBoat) — Malody API 设计参考
Malody — 游戏数据来源
baimg — 背景图床
AI Agent：Claude Gemini

License

MIT

Navigation Menu

Repository navigation

About

Repository files navigation

Malody API

图片演示

功能概览

关于仓库

快速开始

API 端点

图片临时 URL

排行榜

玩家

玩家趋势分析

谱面

游戏模式

评级系统

响应格式

项目结构

技术栈

鸣谢

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
assets		assets
demo		demo
image		image
routers		routers
static/temp		static/temp
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
malody_client.py		malody_client.py
run.py		run.py

Latest commit

History

Folders and files

Repository files navigation

Malody API

图片演示

功能概览

关于仓库

快速开始

API 端点

图片临时 URL

排行榜

玩家

玩家趋势分析

谱面

游戏模式

评级系统

响应格式

项目结构

技术栈

鸣谢

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages