DEVELOPER DOCUMENTATION

公共数据 API

通过 HTTP 查询已发布的游戏、曲目、游戏内收录、曲师、曲包与难度位。公共接口只读，无需身份验证。

Base URLhttps://api.musicgame.wiki查看完整 Schema

快速开始

以下请求搜索曲名中包含 Quon 的曲目，并最多返回两条记录。

cURL

curl --get "https://api.musicgame.wiki/v1/songs" \
  --data-urlencode "q=Quon" \
  --data-urlencode "limit=2"

JavaScript

const response = await fetch(
  'https://api.musicgame.wiki/v1/songs?q=Quon&limit=2'
)

if (!response.ok) {
  throw new Error(`API request failed: ${response.status}`)
}

const { data, pagination } = await response.json()

下一步

列表请求返回 data 与 pagination；详情请求只返回 data。生产环境请将 Base URL 替换为实际部署域名。

请求约定

格式

请求与响应使用 UTF-8。成功响应为 application/json，错误响应为 application/problem+json。

发布状态

公共接口只返回已发布记录，不包含草稿。管理接口使用另一套路径与身份验证，不在本文档范围内。

资源定位

游戏、曲目和曲师详情使用 slug；曲包使用 gameSlug + slug；收录详情使用 UUID。

空值

null 表示该字段没有已填写数据，不等于数字 0、空字符串或布尔值 false。

日期与时间

日期使用 YYYY-MM-DD；时间戳使用带时区的 ISO 8601 字符串；时长统一使用毫秒。

图片

图片字段包含 url、thumbnailUrl（176px）和 previewUrl（320px）。返回的是相对路径，需拼接服务域名。

分页

资源列表使用游标分页。翻页时保留原来的关键词与筛选参数，并追加返回的 nextCursor。

参数	类型	说明
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

列表响应结构

{
  "data": [
    { "id": "7f56a2bc-86ea-4f0e-a758-b1a028f26d90", "slug": "example" }
  ],
  "pagination": {
    "limit": 20,
    "nextCursor": "eyJ2YWx1ZSI6Ii4uLiJ9",
    "hasMore": true
  }
}

当 hasMore 为 false 时，nextCursor 为 null，表示没有下一页。全库搜索与难度位接口不使用游标分页。

下一页请求

curl --get "https://api.musicgame.wiki/v1/songs" \
  --data-urlencode "q=Quon" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=上一页返回的 nextCursor"

缓存与条件请求

公共 GET 响应带有 ETag 和 Cache-Control: public, max-age=30, stale-while-revalidate=60。客户端与 CDN 可以复用响应，并在重新验证时发送 If-None-Match。

条件请求

curl "https://api.musicgame.wiki/v1/games?limit=20" \
  -H 'If-None-Match: "首次响应中的 ETag"'

内容未变化时服务返回 304 Not Modified，响应体为空，客户端应继续使用本地缓存内容。

错误处理

错误响应遵循 Problem Details 结构。code 适合程序判断，detail 用于日志与调试；排查时可同时记录 requestId。

application/problem+json

{
  "type": "https://musicgamewiki.local/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "端点或资源不存在",
  "instance": "/v1/songs/not-a-song",
  "code": "NOT_FOUND",
  "requestId": "req-01J..."
}

状态码	常见 code	处理方式
404	`NOT_FOUND`	检查路径、slug 或 UUID，以及记录是否已发布。
422	`VALIDATION_ERROR`	检查参数类型、取值范围与必填项；响应可能包含 `errors` 数组。
500	`INTERNAL_ERROR`	记录 requestId，稍后重试；不要无限立即重试。
503	`QUERY_TIMEOUT`	缩小筛选范围后重试。

全库搜索

在一次请求中检索游戏、曲目、曲师和曲包。搜索不包含游戏内收录，也不返回分页游标。

GET/v1/search在线请求 ↗

按关键词返回四类资源，每类数量由 limit 分别限制。

参数	类型	说明
`q`必填	`string`	搜索关键词，去除首尾空白后为 1–200 个字符。
`type`	`enum`	可选：games、songs、artists、packs。省略时搜索全部四类。
`limit`	`integer`	每类返回数量，1–20，默认 8。

响应结构

{
  "data": {
    "games": [],
    "songs": [],
    "artists": [],
    "packs": []
  }
}

游戏

游戏包含名称、简称、运营状态、服务地区、上线日期、分地区官网与封面。

GET/v1/games在线请求 ↗

获取游戏列表，支持名称与简称搜索。

参数	类型	说明
`q`	`string`	可选关键词，最长 200 个字符。
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

GET/v1/games/:slug

通过游戏 slug 获取单款游戏。

参数	类型	说明
`slug`必填	`string`	路径参数。小写字母、数字与连字符组成的游戏标识。

曲目

曲目保存跨游戏身份、BPM、封面与署名。音源时长、曲包、地区和谱面不在曲目本体中，请查询游戏内收录。

GET/v1/songs在线请求 ↗

获取曲目列表，支持关键词与曲师筛选。

参数	类型	说明
`q`	`string`	可选曲名关键词，最长 200 个字符。
`artistId`	`UUID`	只返回署名中包含指定曲师的曲目。
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

GET/v1/songs/random在线请求 ↗

从全部已发布曲目中随机抽样。直接返回 data 数组，不包含 pagination。

参数	类型	说明
`limit`	`integer`	随机返回数量，1–20，默认 10。曲目总数不足时返回全部已发布曲目。

GET/v1/songs/:slug

通过曲目 slug 获取单首曲目及完整署名。

参数	类型	说明
`slug`必填	`string`	路径参数。曲目详情地址中使用的标识。

游戏内收录

一次收录表示一首曲目在某款游戏、某个服务地区中的独立记录，包含实际音源时长、曲包、上下架状态、原版收录标记与谱面。

GET/v1/appearances在线请求 ↗

获取收录列表，可按游戏、曲目、曲包及音源时长范围筛选。

参数	类型	说明
`q`	`string`	搜索曲名、游戏或曲包，最长 200 个字符。
`gameId`	`UUID`	按游戏筛选。
`songId`	`UUID`	按曲目筛选，可用于比较同一曲目在不同游戏中的收录。
`packId`	`UUID`	按曲包筛选。
`minDurationMs`	`integer`	最短音源时长，单位为毫秒，必须大于 0。
`maxDurationMs`	`integer`	最长音源时长，单位为毫秒，必须大于 0。
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

GET/v1/appearances/:id

通过 UUID 获取单次收录及 charts 谱面数组。

参数	类型	说明
`id`必填	`UUID`	路径参数。收录没有 slug，不能使用曲目或游戏 slug 代替。

时长与原版收录

durationMs 只属于当前游戏收录；null 表示未记录，不能从其他游戏回填。original 的 null 仅表示编辑者未填写，应与 true、false 分开处理。

曲师

曲师资源表示作曲、编曲、作词、演唱及其他署名身份，包含英文名义、国家或地区与别名。

GET/v1/artists在线请求 ↗

获取曲师列表，支持名义、英文名义与别名搜索。

参数	类型	说明
`q`	`string`	可选关键词，最长 200 个字符。
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

GET/v1/artists/:slug

通过曲师 slug 获取单个署名身份。

参数	类型	说明
`slug`必填	`string`	路径参数。曲师详情地址中使用的标识。

曲包

曲包、版本、章节、分类与活动统一使用曲包资源，并通过 dimension 区分。

GET/v1/packs在线请求 ↗

获取曲包列表，支持名称搜索与游戏筛选。

参数	类型	说明
`q`	`string`	可选曲包名称关键词，最长 200 个字符。
`gameId`	`UUID`	只返回指定游戏内的曲包。
`limit`	`integer`	每页数量，1–100，默认 20。
`cursor`	`string`	上一页返回的 nextCursor；原样传入，不要解析或自行构造。

GET/v1/packs/:gameSlug/:slug

通过游戏 slug 与曲包 slug 获取曲包。曲包 slug 只在所属游戏内唯一。

参数	类型	说明
`gameSlug`必填	`string`	路径参数。所属游戏的 slug，也可从列表项 gameSlug 字段取得。
`slug`必填	`string`	路径参数。曲包自身的 slug。

难度位

难度位定义属于具体游戏，用于解释谱面中的难度名称、简称、排列顺序和主题颜色。

GET/v1/difficulty-slots在线请求 ↗

获取难度位数组。该接口直接返回 data 数组，不包含 pagination。

参数	类型	说明
`gameId`	`UUID`	可选。只返回指定游戏的难度位；省略时返回全部已发布游戏的难度位。

数据与枚举

常用字段

字段	所在资源	含义
`revision`	所有核心资源	记录的修订版本号，不是 API 版本。
`updatedAt`	所有核心资源	记录最后更新时间，ISO 8601 时间戳。
`credits`	Song	有序署名数组；role 表示职责，creditedAs 保存实际显示名义。
`websites`	Game	按服务地区区分的官方网站数组，每个地区最多一个地址。
`charts`	Appearance	谱面数组；levelRaw 保留原始等级文本，slot 关联游戏难度位。
`durationVerifiedAt`	Appearance	当前收录音源时长的核对时间；时长未记录时为 null。
`availableFrom / availableTo`	Appearance	当前收录的上线与下架日期；下架日期只在已下架状态时有值。

枚举值

字段	允许值
`region`	`global` 国际、`jp` 日本、`cn` 中国、`kr` 韩国、`sea` 东南亚
`serviceStatus`	`active` 运营中、`ended` 已停运、`upcoming` 未上线、`unknown` 未知
`status`	`available` 可用、`delisted` 已下架
`dimension`	`pack` 曲包、`version` 版本、`chapter` 章节、`genre` 分类、`event` 活动
`role`	`composer` 作曲、`arranger` 编曲、`lyricist` 作词、`vocalist` 演唱、`other` 其他

完整字段、嵌套对象、数值范围和响应 Schema 以 OpenAPI 交互文档为准。