---
url: https://wiki.awmc.team/dev/assets-api.md
---
# 🖼️ Assets 静态资源 & 谱面资源 API

AWMC 的静态图片、谱面索引、原始文件与单曲打包，统一从 **[download.wmc.pub](https://download.wmc.pub)**（谱面下载站）访问。

公开接口**免鉴权**：自 2026-09-29 起，**单曲**（maidata / 音源 / 曲绘 / PV，以及这首曲子的 zip、adx）**不再要求人机验证**；版本包、全版本包、删除曲包及自定义多选等批量下载仍需验证码。

> 旧资源域名已停用，不能只替换域名继续使用 `/covers/:id`；请改用下面的实际封面路径或单曲文件入口。文件请求可能重定向到对象存储 CDN，请允许跟随重定向。
>
> 已于 2026-10-27 对照 MaiArchive 源码与生产只读 HTTP 核验：封面、单曲信息与文件清单可访问；示例响应仅展示部分字段，文件与大小以实时清单为准。

## 1. 资源根地址

| 根地址 | 内容 |
|---|---|
| `https://download.wmc.pub` | 曲绘等静态图片、谱面文件、谱面索引、单曲打包 |

## 2. 曲绘封面

封面按版本目录与曲目目录访问，不使用旧曲绘 ID 或 `.png` 后缀。目录名取自 3.1 的 `versionFolder` / `folderName`，或 3.3 的 `versionFolder` / `songFolder`；构造 URL 时分别编码每段目录名。

例如：`https://download.wmc.pub/cdn/v1/img/BUDDiES/Apollo%20%5BDX%5D?w=480`。谱面包内原始曲绘见 3.5。

## 3. download.wmc.pub — 谱面资源

### 3.1 谱面列表 / 搜索

全站谱面索引：关键词、版本、类型、流派、删除曲、是否有 PV 都能过滤，分页返回。适合做外部工具、机器人、统计。

> 也支持 `version`（版本名或 `versionid`）、`genre`、`oc`（1/0）、`hasVideo`（1/0）、`page`、`raw=1`（保留原始记录字段）。
> 别名入口：`GET /cdn/v1/data/charts`。

### 3.2 单曲信息

### 3.3 单曲文件清单（拿到直链）

### 3.4 直接取一个文件

免人机验证，点开即下。允许的文件名：`maidata.txt`、`track.mp3`、`track.ogg`、`bg.png`、`bg.jpg`、`pv.mp4`；加 `?dl=1` 走浏览器下载而不是页内播放/预览。

也支持用目录名访问：`GET /f/<版本目录>/<曲目目录>/<文件名>`，例如
`https://download.wmc.pub/f/BUDDiES/Apollo%20%5BDX%5D/maidata.txt`；同名清单是 `GET /f/<版本目录>/<曲目目录>`。

### 3.5 曲绘预览

> 2026-10-27 实测：`/s/011661/bg.png`、`/s/011661/track.mp3` 与目录形式的原图入口返回 **302**，目标为 `oss.awmc.cc`。Node fetch 及从 Wiki 页面发起的浏览器 fetch 跟随并请求 `Range: bytes=0-31` 后均得到 **206**，类型分别为 `image/png` / `audio/mpeg`，最终响应带 `Access-Control-Allow-Origin: *`；`maidata.txt` 则直接返回 **200** 文本，不是所有文件都跳转。部分客户端探测（urllib HEAD / 单字节 Range）触发了 Cloudflare **403 / 1010**，排查时应记录客户端、方法与最终响应，不能仅凭 HEAD 或首跳 302 判断下载失败。展示封面也可使用第 2 节的缩略封面入口。

### 3.6 单曲打包（zip / adx）

> 目录名从 3.1 或 3.3 的 `versionFolder` / `songFolder`（= `folderName`）里拿。
> 版本包（约 1GB）、全版本包、删除曲包仍要人机验证：`/api/download-version/:versionId/:format`、`/api/download-all-versions/:format`、`/api/download-oc/:format`。

## 4. 使用说明

* **无需鉴权**：以上接口都可匿名直接调用；JSON 响应与文件都带 `Access-Control-Allow-Origin: *`，可以直接在网页里 fetch。
* **缓存与重定向**：直接返回的文件通常带 `ETag` 与 `Cache-Control: public`，列表接口支持 `ETag` + 304；跳转响应可能为 `no-store`，请以最终响应头为准。不要硬编码对象存储目标地址，继续使用本站公开入口。
* **限流**：文件接口按 IP 限速（约 600 请求/分钟）；量大的时候请错峰、复用连接，别并发几百个。
* **文件格式**：原始曲绘是 `.png` / `.jpg`，缩略封面还可能返回 WebP（以 `Content-Type` 为准）；音源是 `.mp3` 或 `.ogg`，PV 是 `.mp4`，谱面是纯文本 `maidata.txt`。
* **更新来源**：页面与数据的实时状态以 [download.wmc.pub](https://download.wmc.pub) 为准；谱面预览与评价分析见 [谱面预览 API](/dev/chart-preview-api)。