---
url: https://wiki.awmc.team/en/dev/assets-api.md
---
# 🖼️ Assets & Chart Resource API

AWMC serves static images, the chart index, chart files and single-chart packages through one public entry point: **[download.wmc.pub](https://download.wmc.pub)** (the chart download site).

Public endpoints are **unauthenticated**. Since 2026-09-29, **single-chart** resources (maidata / audio / jacket / PV, plus that chart's zip and adx) **no longer require human verification**. Version packs, the all-versions pack, the deleted-song pack and custom multi-chart downloads still require a captcha.

> The old asset domains are retired. Replacing the hostname is not enough: `/covers/:id` is not supported here. Use the cover route or single-chart file routes below. File requests may redirect to an object-storage CDN; allow redirects.
>
> Verified against MaiArchive source and read-only production HTTP on 2026-10-27: the cover, chart info and file index were accessible. Response examples show selected fields; use the live file index for filenames and sizes.

## 1. Resource root paths

| Root path | Contents |
|---|---|
| `https://download.wmc.pub` | Jackets and static images, chart files, chart index, single-chart packages |

## 2. Cover images

Address covers by version and song folder, not by the old jacket ID or a `.png` suffix. Use `versionFolder` / `folderName` from 3.1, or `versionFolder` / `songFolder` from 3.3; URL-encode each folder segment separately.

Example: `https://download.wmc.pub/cdn/v1/img/BUDDiES/Apollo%20%5BDX%5D?w=480`. For the original jacket inside the chart package, see 3.5.

## 3. download.wmc.pub — chart resources

### 3.1 Chart list / search

A full chart index: filter by keyword, version, chart type, genre, deleted charts and PV availability, with pagination.

> Also supported: `version` (version name or `versionid`), `genre`, `oc` (1/0), `hasVideo` (1/0), `page`, and `raw=1` (keep raw record fields).
> Alias endpoint: `GET /cdn/v1/data/charts`.

### 3.2 Chart info

### 3.3 File list for one chart (direct links)

### 3.4 Fetch a single file

No captcha. Allowed filenames: `maidata.txt`, `track.mp3`, `track.ogg`, `bg.png`, `bg.jpg`, `pv.mp4`. Add `?dl=1` to download instead of playing/previewing inline.

You can also address files by folder: `GET /f/<versionFolder>/<songFolder>/<filename>`, e.g.
`https://download.wmc.pub/f/BUDDiES/Apollo%20%5BDX%5D/maidata.txt`; the matching index is `GET /f/<versionFolder>/<songFolder>`.

### 3.5 Jacket preview

> Verified on 2026-10-27: `/s/011661/bg.png`, `/s/011661/track.mp3` and the directory-based original-image route return **302** to `oss.awmc.cc`. Following with Node fetch and browser fetch from the Wiki, using `Range: bytes=0-31`, returned **206**, with `image/png` / `audio/mpeg` and `Access-Control-Allow-Origin: *` on the final response. `maidata.txt` returned **200** text directly; not every file redirects. Some probes (urllib HEAD / one-byte Range) triggered Cloudflare **403 / 1010**. Record the client, method and final response when diagnosing; HEAD or the initial 302 alone does not establish a failed download. For display, the thumbnail route in section 2 is also available.

### 3.6 Single-chart package (zip / adx)

> Folder names come from the `versionFolder` / `songFolder` (= `folderName`) fields in 3.1 or 3.3.
> Version packs (~1GB), the all-versions pack and the deleted-song pack still require the captcha: `/api/download-version/:versionId/:format`, `/api/download-all-versions/:format`, `/api/download-oc/:format`.

## 4. Usage notes

* **No auth**: every endpoint above is anonymous; JSON responses and files both send `Access-Control-Allow-Origin: *`, so they can be fetched directly from a web page.
* **Caching and redirects**: directly served files generally carry `ETag` and `Cache-Control: public`; the list API supports `ETag` + 304. Redirect responses may use `no-store`; respect the final response headers. Keep using the public entry point rather than hard-coding an object-storage target.
* **Rate limits**: file endpoints are limited per IP (about 600 requests/minute). For bulk work, pace yourself instead of opening hundreds of parallel connections.
* **File formats**: original jackets are `.png` / `.jpg`; thumbnails may also return WebP (check `Content-Type`). Audio is `.mp3` or `.ogg`, PV is `.mp4`, and charts are plain text `maidata.txt`.
* **Source of truth**: see [download.wmc.pub](https://download.wmc.pub) for live state. For chart preview and rating analysis, see the [Chart Preview API](/en/dev/chart-preview-api).