文件上传

POST

/api/v2/upload

上传文件、头像或谱面。谱面上传成功后，服务端会失效相关缓存。type=chart-zip：服务端在内存中解包 zip，逐文件上传到 R2 包前缀 charts/{packageId}/... —— meta.json 始终上传；若存在 extra.json，其本体以及它引用的文件都会上传；zip 内其余资源全部保留（零丢失）。服务端不再保存/生成原始整包 zip，也不再写 file_url；资源清单写入 assets_manifest。成功响应为 { message, id, packageId, warning? }（zip 内缺 meta.json 时带 warning）。

请求参数

Authorization

JWT Bearer

在 Header 添加参数

Authorization

示例：

Authorization: ********************

Query 参数

Body 参数multipart/form-data必填

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://api.xhsr.org.cn/api/v2/upload?type=&filename=' \
--header 'Authorization: Bearer <token>' \
--form 'file=@""' \
--form 'title=""' \
--form 'artist=""' \
--form 'charter=""' \
--form 'difficulty=""' \
--form 'level=""' \
--form 'bpm=""' \
--form 'offset=""' \
--form 'description=""' \
--form 'allow_ai_learning="false"'

返回响应

🟢200

application/json

上传成功。type=chart-zip 返回谱面团包结果 { message, id, packageId, warning? }；type=avatar / type=file 返回 { url }（公开访问地址）。

Bodyapplication/json

示例

{
    "message": "Upload successful",
    "id": 42,
    "packageId": "1765342698163-ab12cd",
    "warning": "meta.json not found in zip; chart/audio/cover resolved by type. A backfill may be needed."
}

🟢201

🟠401

🟠403

🔴500

修改于 2026-10-07 10:19:10

获取 presigned 上传地址 / 头像代理

获取谱面元数据（不再服务端打包 zip）