创云镜像 · API 文档

基础约定

GET/api/v1/stats 站点统计

curl https://mirrors.coreyun.net/api/v1/stats

{
  "size_bytes": 921328712345, "size_human": "858.0 GB",
  "builds": 102486,            // 本地已镜像构建数
  "site_builds": 240000,       // 上游站点构建总数
  "types": 28,                 // 核心类型数
  "last_sync": "2026-08-28T18:50:00+08:00"
}

GET/api/v1/types 核心列表

全部核心类型（28 种，含 YOUER/MAGMA/DIVINEMC 等），每个核心带简介。

curl https://mirrors.coreyun.net/api/v1/types

{
  "base": "https://mirrors.coreyun.net",
  "count": 28,
  "types": [
    {
      "type": "PAPER", "name": "Paper",
      "homepage": "https://papermc.io/software/paper",
      "categories": ["plugins"],
      "category": "插件",
      "description": "基于 Spigot 的高性能插件服务端，大幅优化性能并扩展大量 API，插件服首选。",
      "deprecated": false, "experimental": false,
      "site_builds": 5660, "local_builds": 4321,
      "icon": "https://mirrors.coreyun.net/api/v1/types/PAPER/icon",
      "versions_url": "https://mirrors.coreyun.net/api/v1/types/PAPER/versions"
    }, ...
  ]
}

GET/api/v1/types/{type} 核心详情

单个核心的信息（含简介），结构与上面 types[] 一致。

GET/api/v1/types/{type}/icon 核心图标

curl -O https://mirrors.coreyun.net/api/v1/types/Paper/icon   # image/png

版本与构建（游戏版本 / 构建版本分开）

GET/api/v1/types/{type}/versions 游戏版本列表

curl https://mirrors.coreyun.net/api/v1/types/Paper/versions

{
  "type": "PAPER", "name": "Paper", "count": 66,
  "game_versions": ["26.2", "26.1.2", "26.1.1", "…", "1.8.8"]
}

GET/api/v1/types/{type}/versions/{game} 构建版本列表

某游戏版本下的构建版本，每个构建含下载直链与 SHA-256。支持分页参数 limit/offset。

curl "https://mirrors.coreyun.net/api/v1/types/Paper/versions/1.21.4?limit=10&offset=0"

{
  "type": "PAPER", "name": "Paper", "game_version": "1.21.4",
  "count": 224, "limit": 10, "offset": 0,
  "builds": [
    {
      "build": "#232", "folder": "#232",
      "uuid": "e60f6fa0-ae4d-480b-b4dd-56af5afd48bf",
      "project_version": null, "created": "2025-06-09T12:18:55.778Z",
      "experimental": false, "changes": ["Fix infinite loop in RegionFile IO"],
      "files": [
        {"file": "paper-1.21.4-232.jar", "size": 51437498,
         "sha256": "5ee4f5…eaffc",
         "url": "https://mirrors.coreyun.net/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar"}
      ]
    }, ...
  ]
}

GET/api/v1/types/{type}/versions/{game}/{build} 单个构建详情

结构同 builds[]（外加 type/name/game_version）。{build} 可用构建名或目录名。

GET/api/v1/download 下载跳转（302）

curl -L "https://mirrors.coreyun.net/api/v1/download?type=Paper&game=1.21.4&build=%23232&file=paper-1.21.4-232.jar" -o paper.jar

文件下载与断点续传

下载直链格式：/dl/{核心名}/{游戏版本}/{构建}/{文件名}（各段 URL 编码）。

• 支持 Range（HTTP 206），断点续传：curl -C - -O URL
• .jar/.zip 自动带下载头（Content-Disposition: attachment）
• 每个文件同目录有 <文件名>.sha256 文本文件，供完整性校验

# 断点续传
curl -C - -o paper.jar "https://mirrors.coreyun.net/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar"

# SHA-256 校验
curl -s "https://mirrors.coreyun.net/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar.sha256"
sha256sum paper.jar

错误码

完整示例

BASE=https://mirrors.coreyun.net

# 1. 站点统计
curl $BASE/api/v1/stats

# 2. 核心列表（含简介）
curl $BASE/api/v1/types

# 3. Paper 的游戏版本
curl $BASE/api/v1/types/Paper/versions

# 4. 1.21.4 的构建版本（分页: 每批 10 个）
curl "$BASE/api/v1/types/Paper/versions/1.21.4?limit=10&offset=0"

# 5. 单个构建
curl $BASE/api/v1/types/Paper/versions/1.21.4/%23232

# 6. 直链下载（断点续传）
curl -C - -o paper.jar $BASE/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar