开放 API

以 REST / JSON 读取展览大厅的作品数据。

开放 API

红石阁 公开 API 文档

这份文档面向想接入红石阁公开数据的开发者。下面列出的接口都不需要登录，也不用任何凭证，直接请求就能拿到数据。

所有接口地址都以 /api 开头，返回的数据基本都是 JSON 格式。

目录

  1. 作品列表
  2. 作品详情
  3. 在线预览结构
  4. 下载结构文件
  5. 作品评论列表
  6. 用户公开主页
  7. 创作者订阅人数
  8. 称号列表
  9. 创作者排行榜
  10. 铭文 / 记录列表
  11. 页面
  12. 速查表

1. 作品列表

GET /api/doors

这是作品档案馆的主列表，返回的都是已经过审核的作品，默认按发布时间从新到旧排。

查询参数（都是可选的）

参数 作用
size 按开启尺寸筛选，比如 3x3
door_type 按分类筛选，比如 piston_door
speed 传 high 只看高速作品
compact 传 high 只看紧凑作品
version 按已测试版本筛选
edition 按游戏版本筛选（Java / 基岩）
user 按作者筛选，看某个创作者的全部作品
page 页码，默认第 1 页
per_page 每页几条，默认 60

返回示例

{
  "doors": [
    {
      "id": "abc123",
      "name": "双触发活塞门",
      "author": "Steve",
      "door_type": "piston_door",
      "opening_size": "3x3",
      "high_speed": false,
      "high_compact": true,
      "tested_versions": ["1.20", "1.21"],
      "size": [3, 3, 1],
      "block_count": 142,
      "tags": [],
      "has_preview": true,
      "has_open": true,
      "thumb_url": "/work/abc123/thumb.png",
      "poster_url": "/work/abc123/poster.png"
    }
  ],
  "page": 1,
  "per_page": 60,
  "has_more": true
}

怎么用

# 翻到第 2 页，只看活塞门，每页 30 条
GET /api/doors?door_type=piston_door&page=2&per_page=30

# 看某个创作者的全部作品
GET /api/doors?user=u_88

# 只看高速 + 紧凑的
GET /api/doors?speed=high&compact=high

# 按 1.21 版本筛
GET /api/doors?version=1.21

几个要说明的点：

  • thumb_url 和 poster_url 是缩略图和海报地址，能直接拿去前端展示。但不是每件作品都有——只有这件作品实际生成了对应图片，才会带这俩字段，没有就不出现。至于图片是 .webp 还是 .png，也由实际文件决定，地址里会带上。
  • has_more 表示后面还有没有更多内容。不过它的判断方式有点粗：只要本页返回的条数等于 per_page，就认为「还有更多」。所以最后一页如果恰好满页，has_more 会是 true 但其实没下一页了。翻页时建议同时看「实际返回条数」，不够 per_page 就到头了。
  • size 是作品的体积，格式是 [x, y, z] 三个数。
  • 列表里的作品都是已过审的，未过审的不会出现。

2. 作品详情

GET /api/doors/{id}

传一个作品 ID，返回这件作品的完整信息。找不到就返回 404。

GET /api/doors/abc123

{
  "id": "abc123",
  "name": "双触发活塞门",
  "description": "……",
  "door_type": "piston_door",
  "opening_size": "3x3",
  "high_speed": false,
  "high_compact": true,
  "tested_versions": ["1.20", "1.21"],
  "size": [3, 3, 1],
  "block_count": 142,
  "tags": ["redstone", "hidden"],
  "meta": { "edition": "java" },
  "created_at": "2025-01-01T00:00:00Z"
}

meta 里装的是这件作品的附加信息（比如 Java / 基岩版标识之类），具体有哪些字段取决于作品本身，不同作品可能不一样。

3. 在线预览结构

GET /api/doors/{id}/template

返回这件作品的结构预览数据（JSON 格式），可以直接拿去做网页里的 3D 预览。如果这件作品没有结构数据，会返回 404。

GET /api/doors/abc123/template

4. 下载结构文件

GET /api/doors/{id}/file/{which}

下载作品的结构文件。只有过审的作品才能公开下载，没过审或下架的不开放。

{which} 告诉后端你要取哪一份文件，能填这几个值：

值 是什么
open 开启态结构（Java 版）
close 关闭态结构（Java 版）
preview 预览结构
open_be 开启态结构（基岩版）
close_be 关闭态结构（基岩版）

关于文件后缀：你不用、也没法指定要 .nbt 还是 .mcstructure。后端会根据 {which} 找到这件作品对应的那份文件，原样发给你——Java 版作品存的是什么格式，下载下来就是什么格式，基岩版同理。也就是说，后缀由作品本身决定，调用方管不了。

如果某件作品没有对应的那份文件（比如基岩版作品没传 open_be），会返回 404。

# 下载 Java 版的开启态结构
GET /api/doors/abc123/file/open

# 下载基岩版的关闭态结构
GET /api/doors/abc123/file/close_be

# 下载预览结构
GET /api/doors/abc123/file/preview

前端用的时候直接 <a href="..." download> 就能触发浏览器下载。

5. 作品评论列表

GET /api/doors/{id}/comments

返回这件作品的全部评论。同样只有过审的作品才开放评论查看。没登录的时候，每条评论的 liked 都是 false。

GET /api/doors/abc123/comments

{
  "comments": [
    {
      "id": "c_1",
      "author": "Alex",
      "body": "太强了！",
      "parent_id": null,
      "reply_to": null,
      "likes": 5,
      "liked": false,
      "title": { "id": "t_1", "name": "红石大师" },
      "created_at": "2025-01-02T00:00:00Z"
    }
  ]
}

几个字段说明：

  • liked 表示「当前请求者有没有点过这条赞」。因为这是免登录接口，没人登录，所以永远是 false。
  • parent_id 和 reply_to 是回复关系：parent_id 是这条回复所属的根评论 ID，reply_to 是它直接回复的那条评论 ID。不是回复的话这俩都是 null。
  • title 是评论者当前装备的称号，没有装备就是 null。
  • likes 是这条评论收到的点赞数。

6. 用户公开主页

GET /api/users/{id}

返回某个用户的公开资料和他已过审的全部作品。不需要登录。

GET /api/users/u_1

{
  "user": {
    "id": "u_1",
    "account_name": "steve",
    "game_name": "Steve",
    "bio": "红石爱好者",
    "titles": [ { "id": "t_1", "name": "红石大师" } ],
    "title": { "id": "t_1", "name": "红石大师" }
  },
  "doors": [ { "id": "abc123", "name": "双触发活塞门" } ]
}

这里返回的只是用户自己公开出来的信息（昵称、简介、称号、作品），不涉及任何隐私数据。

7. 创作者订阅人数

GET /api/creators/{id}/subscription

返回某个创作者被多少人订阅。没登录的话，subscribed 一直是 false。

GET /api/creators/u_1/subscription

{ "count": 128, "subscribed": false }

8. 称号列表

两个接口：

  • GET /api/titles —— 站内全部称号
  • GET /api/users/{id}/titles —— 某个用户拥有的全部称号
GET /api/titles
GET /api/users/u_1/titles

{ "titles": [ { "id": "t_1", "name": "红石大师", "desc": "……" } ] }

9. 创作者排行榜

GET /api/creators/top

创作者排行榜，按作品数、方块数这些排，分页返回。

参数 作用
limit 每页几条，默认 24
offset 跳过几条，默认 0 
GET /api/creators/top?limit=10&offset=0

{
  "creators": [
    {
      "id": "u_1",
      "account_name": "steve",
      "works": 12,
      "blocks": 1820,
      "followers": 128
    }
  ],
  "total": 56,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

10. 铭文 / 记录列表

GET /api/records

站内的「铭文 / 记录」列表，可以按关键词搜，也能分页。

参数 作用
q 搜索关键词
page 页码，默认 1
per_page 每页几条，默认 9 
GET /api/records?q=活塞&page=1&per_page=9

{
  "records": [
    {
      "id": "abc123",
      "name": "双触发活塞门",
      "author": "Steve",
      "door_type": "piston_door",
      "opening_size": "3x3",
      "record": {
        "note": "经典之作,收录纪念"
      }
    }
  ],
  "total": 30,
  "page": 1,
  "per_page": 9,
  "pages": 4
}

11. 页面

下面这几个是网页页面，不是 JSON 接口，但同样不需要登录，浏览器里直接打开就行：

地址 是什么
GET /work/{id} 作品详情页
GET /creator/{id} 创作者主页 
https://your-host/work/abc123
https://your-host/creator/u_1

12. 速查表

接口 要登录吗 返回什么
GET /api/doors 不用 JSON
GET /api/doors/{id} 不用 JSON
GET /api/doors/{id}/template 不用 JSON（结构预览）
GET /api/doors/{id}/file/{which} 不用 文件流
GET /api/doors/{id}/comments 不用 JSON
GET /api/users/{id} 不用 JSON（公开资料）
GET /api/creators/{id}/subscription 不用 JSON
GET /api/titles 不用 JSON
GET /api/users/{id}/titles 不用 JSON
GET /api/creators/top 不用 JSON
GET /api/records 不用 JSON
GET /work/{id} 不用 HTML
GET /creator/{id} 不用 HTML

几点说明

  • 作品搜索：列表接口目前只能按分类、尺寸、版本这些条件筛，还不能按作品名模糊搜索。
  • 下载限制：没过审的作品不开放下载。
  • 用户资料：用户主页接口只返回用户自己公开的信息和作品，不含隐私数据。
  • 文件格式：下载结构和图片地址里的后缀（.nbt / .mcstructure、.webp / .png 等）都由作品实际存的文件决定，调用方指定不了，地址里会带出来。
  • 分页：列表类接口的 has_more 用「本页条数等于每页条数」来判断，最后一页恰好满页时会误报「还有更多」，翻页时建议同时看实际返回的条数。
  • 评论点赞：免登录看评论时，liked 永远是 false，因为没人登录就无所谓「我有没有点过赞」。