API 接口文档 - MC建筑工具箱

接口基础地址

https://buildtool.xiaozhouweb.com/api/

除标注「返回文件下载」的接口外，全部返回 application/json；跨域已放开（CORS *），可直接在网页 / 小程序 / 脚本中调用
出错时返回对应 HTTP 状态码 + {"success": false, "error": "原因"}（结构定位接口用 ok 字段）
文件上传上限 1024MB，转换类接口服务端超时 1800 秒
「返回文件下载」的接口输出二进制 + Content-Disposition: attachment，文件名可从该响应头读取

查询类

无需上传文件，浏览器直接打开即可调用

GET /api/mcid.php 在线测试

MCID 查询

输入中文名或英文 ID，查询基岩版 / Java 版的方块、物品、实体、音效等 ID

参数	类型	必填	说明
q	string	是	查询词，支持中文名 / 英文 ID / minecraft: 前缀
ed	string	否	版本：bedrock（默认）/ java
cat	string	否	限定分类，默认 all；分类清单用 list=1 获取
mode	string	否	匹配方式：contains（默认）/ exact / startswith
limit	int	否	返回条数上限，1-500，默认 50
list	int	否	传 1 时只返回分类清单，不查询

响应示例

{
  "success": true,
  "edition": "bedrock",
  "version": "1.26.52.3",
  "query": "钻石",
  "total": 74,
  "shown": 2,
  "groups": [
    {
      "cat": "item",
      "cat_cn": "物品",
      "items": [
        { "key": "diamond", "id": "diamond", "zh": "钻石", "en": "Diamond" }
      ]
    }
  ],
  "took_ms": 4.9
}

基岩版 id 为游戏内命令的实际形态（方块/物品等裸 ID，fog、biome、camera_preset、loot_tool 等自带 minecraft:）；Java 版 id 统一带 minecraft: 前缀。

GET /api/cmdhelper.php 在线测试

命令助手查询

命令参数枚举查询：setblock / fill / clone / structure / gamemode / dimensions 等参数的可选值与中文说明

参数	类型	必填	说明
q	string	否	查询词，中英双向匹配（匹配取值或中文说明）；留空 = 列出前 limit 条
cat	string	否	分类键，默认 all（全部参数枚举）；清单用 list=1
limit	int	否	每分类返回条数上限，1-300，默认 50
list	int	否	传 1 时只返回分类清单

响应示例

{
  "success": true,
  "query": "冒险",
  "cat": "gamemode",
  "total": 1,
  "groups": [
    {
      "cat": "gamemode",
      "cat_cn": "游戏模式",
      "items": [
        ["adventure", "冒险模式"]
      ]
    }
  ],
  "took_ms": 38.2
}

数据来自「命令助手」内建命令库（Reforged），仅含命令参数枚举（setblock/fill/clone/structure 旧方块处理、游戏模式、维度、比较运算符等）。ID 汉化查询请用 MCID 查询接口。

GET /api/mapquery.php 在线测试

结构定位

按种子计算基岩版（1.18+，与 Java 版同算法）结构的潜在生成位置

参数	类型	必填	说明
seed	int	是	世界种子（整数）
type	string	否	结构类型，默认 village
x	int	否	搜索中心 X，默认 0
z	int	否	搜索中心 Z，默认 0
range	int	否	搜索半径（方块），256-20000，默认 2048

响应示例

{
  "ok": true,
  "type": "village",
  "name": "村庄",
  "seed": 12345,
  "spacing": 34,
  "biome_dependent": true,
  "center": { "x": 0, "z": 0 },
  "radius": 2048,
  "count": 1,
  "positions": [
    { "x": 240, "z": -336, "chunk_x": 15, "chunk_z": -21 }
  ]
}

type 可选：village / pillager_outpost / desert_temple / jungle_temple / witch_hut / igloo / ocean_monument / woodland_mansion / shipwreck / ocean_ruin / ruined_portal / ancient_city / trail_ruins / trial_chambers / buried_treasure。注意本接口用 ok 字段表示成功。结果为按种子算出的潜在位置，村庄等是否生成还取决于生物群系。

GET /api/textures.php

材质贴图映射

返回方块名 → 贴图文件名（top/side/bottom 三面）的映射表，贴图文件在 /textures/ 目录

响应示例

{
  "success": true,
  "data": {
    "textures": {
      "minecraft:oak_log": {
        "top": "oak_log_top",
        "side": "oak_log",
        "bottom": "oak_log_top"
      },
      "minecraft:oak_planks": {
        "top": "oak_planks",
        "side": "oak_planks",
        "bottom": "oak_planks"
      }
    },
    "availableFiles": ["oak_log", "oak_log_top", "oak_planks", "..."]
  }
}

贴图文件访问路径：/textures/{文件名}.png。映射约 8700 条，贴图约 4000 张。

格式转换

POST 上传文件，返回转换后的文件下载（出错时返回 JSON）

POST /api/convert.php

建筑格式互转

20+ 种建筑格式互转：mcstructure / bdx / litematic / mcworld / schem / 网易加解密格式 / 各类建筑工具格式

参数	类型	必填	说明
file	file	是	上传的建筑文件（自动识别源格式）
target	string	是	目标格式，见下方列表
mcf_cbd / mcf_pattern / mcf_version / mcf_x / mcf_z	mixed	否	源为 .mcfunction / .cbd 时的解析参数
mcw_x / mcw_y / mcw_z	int	否	源为 mcworld 时的坐标偏移

成功时返回二进制文件下载（出错返回 JSON）

target 可选：fuhongbuild / sheep / original / fuhongsound / mcstructure / bdx / schem / schematic / litematic / nbt / mcworld / mcfunction / txt / sibi / reb / qingxu / timebuilder / kbdx / ibi / bds / tibi / bcf / runaway_json。文件上限 1024MB，服务端超时 1800 秒，成功返回二进制文件下载。

POST /api/cmdtools.php

指令工具（命令批量处理）

tag 标签批量加 / 前缀字符批量加 / deny 保护层计算 / cbjson→txt 导入 / bdx·mcstructure·bxy 提取命令 JSON / bdx 指令更新

参数	类型	必填	说明
file	file	是	txt / mcfunction 命令列表，或 bdx / mcstructure / bxy（extract、bdxcmd）
action	string	是	addtag（tag 批量加）/ prefix（前缀批量加）/ deny（deny 计算）/ json2txt（JSON 转 TXT）/ extract（提取命令 JSON）/ bdxcmd（指令更新）
tag / sel	string	addtag	标签名；sel 为生效选择器，逗号分隔，默认 s,p,a,r,e
prefix / suffix	string	prefix	行首 / 行尾追加内容
find / replace	string	bdxcmd	查找与替换的命令片段（仅作用于命令字段），输出同格式文件

成功时返回二进制文件下载（出错返回 JSON）

全部返回文件下载（txt / json / bdx / mcstructure）。deny 依据 setblock 相对坐标计算建筑下方 1 格的正方形保护层；extract 与文件互转的「命令方块详情」为同一格式。

POST /api/netease.php

网易存档加解密

网易基岩版存档（.mcworld / .zip / 单个 db 文件）解密与加密

参数	类型	必填	说明
file	file	是	上传的存档文件
action	string	是	analyze（分析加密状态）/ process（执行加解密）
mode	string	action=process 时必填	decrypt / encrypt
output	string	否	process 时输出格式：zip / mcworld（对单文件输入无效）

响应示例

{
  "success": true,
  "inputType": "zip",
  "encrypted": true,
  "encryptedCount": 12,
  "totalFiles": 345,
  "worldName": "我的世界",
  "hasDb": true,
  "hasLevelDat": true,
  "baseDir": "MyWorld",
  "levelDatReadable": true,
  "leveldbReadable": true
}

analyze 返回上示 JSON；process 返回处理后的文件下载。

POST /api/rotate.php

BDX 旋转

将 BDX 建筑按 90° / 180° / 270° 顺时针旋转后返回新文件

参数	类型	必填	说明
file	file	是	上传的 BDX 文件
angle	int	否	旋转角度：90（默认）/ 180 / 270

成功时返回二进制文件下载（出错返回 JSON）

返回旋转后的 BDX 二进制文件下载。

POST /api/mcfunction.php

MC 函数转换

把 .mcfunction / .cbd / .txt 命令文件转换为 bdx / mcstructure / mcpack

参数	类型	必填	说明
file	file	是	上传的命令文件
output	string	否	输出格式：mcstructure（默认）/ bdx / mcpack
version	string	否	命令版本
pattern	string	否	命令行匹配模板，默认 %{command}%
x	int	否	区域宽度，默认 8
z	int	否	区域长度，默认 8
cbd	string	否	CBD 命令方块数据相关参数

成功时返回二进制文件下载（出错返回 JSON）

音乐处理

POST 上传 MIDI / NBS，生成音符盒相关产物

POST /api/midi.php

MIDI / NBS 转音符盒

MIDI / NBS 音乐转 mcstructure / bdx / mcpack / mcfunction / txt

参数	类型	必填	说明
file	file	是	上传的 .mid / .nbs 文件
action	string	否	info（返回元数据，默认）/ convert（执行转换）
output_format	string	否	mcstructure / bdx / mcpack / mcfunction / mcfunction-txt / txt
speed	float	否	播放速度倍率
volume / sub_volume / main_volume	float	否	音量相关
pitch_shift	int	否	整体音高偏移
ignore_percussion	int	否	忽略打击乐通道
instrument_map	string	否	乐器映射
progress_bar / player / lyrics_player / lyrics_color	mixed	否	播放器与歌词显示
x_length / z_length	int	否	建筑尺寸

响应示例

{
  "success": true,
  "info": {
    "fileName": "song.mid",
    "timeTotal": 182.5,
    "tracksCount": 8,
    "noteCount": 4231,
    "lyricsCount": 0
  }
}

action=info 返回上示 JSON；action=convert 返回对应格式的文件下载。其余可选参数与站内「MIDI 转换器」工具一致。

POST /api/midi_nbs.php

MIDI ↔ NBS 互转

MIDI 转 NBS、NBS 转 MIDI 双向互转

参数	类型	必填	说明
file	file	是	上传的 .mid 或 .nbs 文件
action	string	否	info（识别文件并返回元数据）/ convert（默认，执行互转）
song_name	string	否	MIDI → NBS 时的曲名
song_author	string	否	MIDI → NBS 时的作者
tempo	float	否	MIDI → NBS 时的速度

成功时返回二进制文件下载（出错返回 JSON）

convert 时按上传类型自动反向转换，返回文件下载。

POST /api/midi_redstone.php

红石音乐生成

MIDI 转红石音乐投影文件或手动搭建数据

参数	类型	必填	说明
file	file	是	上传的 MIDI 文件
action	string	否	info / convert（默认）
output_format	string	否	litematic（默认）/ schem / nbt / manual
tracks	string	否	JSON 字符串，自定义音轨 [{name, notes:[{pitch, time, duration}]}]，pitch 为 0-24，time 单位秒

成功时返回二进制文件下载（出错返回 JSON）

output_format=manual 时返回搭建说明数据，其余返回对应投影文件下载。

POST /api/note-music.php

NoteBOT 音轨解析

MIDI 转音符盒 NoteBOT 播放脚本（双轨道方案，通道 10 打击乐）

参数	类型	必填	说明
file	file	是	上传的 MIDI 文件
mode	string	否	解析模式
min_gap	int	否	音符最小间隔
percussion_channel	int	否	打击乐通道号
speed	float	否	速度倍率

成功时返回二进制文件下载（出错返回 JSON）

直接返回脚本文本（text/plain），可用于聊天栏或命令方块播放。

图片与动画

POST 上传图片 / 提交文字，生成建筑或命令包

POST /api/pixel.php

图片转像素画

图片按颜色映射为方块，输出像素画 JSON / litematic

参数	类型	必填	说明
file	file	是	上传的 PNG / JPG / BMP 图片
format	string	否	fuhong / sheep / original（返回 JSON）/ litematic（返回文件下载），默认 original
dither	string	否	抖动算法：none（默认）/ floyd / atkinson / stucki / jjn / sierra-lite / ordered / random
strength	float	否	抖动强度 0-2，默认 1（仅抖动算法生效）
match	string	否	色差算法（方块颜色匹配）：rgb（默认，最快）/ redmean / hsv / lab / ciede2000（最准，较慢，大尺寸建议 rgb）
brightness / contrast / saturation	int	否	图像调整 -100~100（亮度 / 对比度 / 饱和度）
remove_white	int	否	智能去白底容差 0-100（0=关闭），从边缘泛洪清除近白背景
smooth / enhance / outline	int	否	传 1 启用：智能平滑 / 色彩增强（对比 ×1.15 饱和 ×1.2）/ 自动描边
preview	int	否	传 1 时只返回量化预览图 {png: dataURL}，不生成文件
width	int	否	目标长度（方块数），默认 64
height	int	否	目标宽度，0 = 等比缩放（默认）
flip_y	int	否	Y 轴翻转
plane / blocks / categories / color	mixed	否	方块调色板与映射控制

成功时返回二进制文件下载（出错返回 JSON）

GET 请求带 ?categories=1 可获取全部方块分类调色板（前端选块器用）。

POST /api/img2mcpack.php

图片转 mcpack

图片每个像素映射为最接近颜色的方块，生成 setblock 命令并打包

参数	类型	必填	说明
file	file	是	上传的图片
platform	string	否	命令平台：BE（默认）/ JE
fitmode	string	否	颜色距离算法：sqr（默认）/ abs
rw / gw / bw	float	否	RGB 通道权重，默认 1
rs / gs / bs	int	否	RGB 缩放百分比，默认 100
ca	float	否	色差惩罚权重，默认 1
xrange / yrange	int	否	分块尺寸 X / Z，默认 16
relpos	string	否	坐标模式：abs（默认）/ rel
guide	int	否	是否生成引导传送命令，默认 0

成功时返回二进制文件下载（出错返回 JSON）

返回 ZIP 文件下载（BE 为 mcpack 行为包，JE 为 zip 命令包）。

POST /api/text2particle.php

文字粒子画

文字渲染后提取像素生成基岩版 particle 命令行为包

参数	类型	必填	说明
text	string	是	要渲染的文本（支持多行）
sx / sy	int	否	画布宽 / 高 px，默认 256
font_size	int	否	字号 px，默认 36
font_path	string	否	字体文件路径（默认自动探测系统字体）
stroke	int	否	0 = 实心（默认）/ 1 = 空心描边
multiline	string	否	多行处理：single（默认）/ overlay / perline
lineh	int	否	单行高度 px（perline 模式），默认 38
pid	string	否	粒子 ID，默认 minecraft:balloon_gas_particle
offset	float	否	坐标缩放，默认 0.5
relpos	string	否	坐标模式：abs（默认）/ rel
flip	int	否	Y 轴翻转，默认 1

成功时返回二进制文件下载（出错返回 JSON）

返回 ZIP 文件下载（mcpack 行为包）。

POST /api/animation.php

动画结构生成器

文字 / 图片转命令方块动画，输出 TXT 或 mcstructure

参数	类型	必填	说明
mode	string	是	text（文字）/ image（图片）
text	string	mode=text 时必填	要渲染的文字
file	file	mode=image 时必填	上传的图片
width / height	int	否	画布尺寸
color_mode	string	否	图片颜色模式：mc / ascii / bw / braille
delay	int	否	帧延时
frames	int	否	帧数
format	string	否	输出格式：txt / mcstructure
player / x_length / z_length	mixed	否	播放器与建筑尺寸

成功时返回二进制文件下载（出错返回 JSON）

按 format 返回 TXT 文本或 mcstructure 二进制文件下载。

预览与文本

建筑解析与文本处理

POST /api/preview_parse.php

建筑预览解析

上传建筑文件，服务端解析为方块数据 JSON（供 Three.js 等前端渲染）

参数	类型	必填	说明
file	file	是	建筑文件（mcstructure / bdx / schem / litematic / mcworld / 网易格式等）

响应示例

{
  "success": true,
  "data": {
    "names": ["minecraft:stone", "minecraft:oak_planks"],
    "blocks": [[0, 0, 0, 0], [1, 0, 0, 1]],
    "states": [[0, {"facing": "north"}]]
  }
}

紧凑格式：blocks 为 [x, y, z, 方块名索引]，names 为方块名表，states 为可选的方块状态。响应超过 100KB 自动 gzip。文件上限 1024MB。

POST /api/pixel_source.php

像素画来源生成

艺术字（含纵向渐变色）与二维码 PNG 生成，作为像素画的来源图；生成逻辑全在服务端

参数	类型	必填	说明
type	string	是	arttext（艺术字）/ qr（二维码）
text	string	是	arttext：文字，支持 \n 多行（最多 8 行，单行 30 字）；qr：内容（最长 800 字符）
color	string	arttext 选填	文字颜色 #RRGGBB，默认 #111111
color2	string	arttext 选填	渐变第二色 #RRGGBB，传入后文字纵向渐变 color→color2
bold / bg	int	arttext 选填	1=粗体（默认）/ 1=白色背景（默认透明）
ecc	string	qr 选填	容错等级 L / M（默认）/ Q / H
size	int	qr 选填	预览图每模块像素数 1-16，默认 8（不影响方块映射）

响应示例

{
  "success": true,
  "source": "qr",
  "png": "data:image/png;base64,...",
  "modules": 29,
  "size": 37
}

返回 PNG 的 dataURL，前端直接作为像素画来源图。二维码自动加 4 模块静区，size=modules+8；配合 pixel.php 的 dither=none 与黑白混凝土调色板可保证扫码可用。

POST /api/geo_builder.php

真实地图生成（1:1）

按真实经纬度范围生成地形与建筑：地形来自高程瓦片，建筑轮廓与材质来自 OpenStreetMap（Arnis 思路的 PHP 实现）

参数	类型	必填	说明
lat / lon	float	二选一	中心经纬度（不传 bbox 时必填）
bbox	string	二选一	矩形范围 "南,西,北,东"，地图框选后自动传入，优先于 lat/lon
radius	int	否	圆形半径（米），20-500，默认 60（未框选时用）
scale	float	否	比例：1 方块 = ? 米，0.5-4，默认 1（1:1 真实比例）
level_h	int	否	每层楼多少米，2-5，默认 3
window / ground	int	否	1=开窗 / 保留地形（默认均开启）

响应示例

{
  "success": true,
  "code": "// 真实世界地图生成 · 1:1 真实比例 …",
  "meta": {
    "buildings": 43, "found": 43, "grid": "161×161",
    "radius": 100, "scale": 1, "level_h": 3,
    "size_m": [160, 160], "terrain": true,
    "source": "OpenStreetMap / Overpass + Terrarium 高程"
  }
}

code 为 VoxelBuilder JS，与 AI 生成的代码走同一套执行/预览/导出链路。地形为 5 格薄壳（表层草/沙 + 泥土 + 石头）并随海拔起伏，水域自动填水；建筑材质按 building / building:material 标签自动选取，1 层 = level_h 米。数据源带缓存（高程瓦片长期缓存、建筑轮廓 24 小时），首次查询需数秒。

POST /api/geo_export.php

真实地图全尺寸导出（绕过预览上限）

浏览器 3D 预览有约 240 格上限，本接口没有：在服务器上按 1:1 完整生成，默认**合并成单个 BDX** 打包下载，跳过页面预览

参数	类型	必填	说明
bbox	string	是	矩形范围 "南,西,北,东"，与 geo_builder 一致
scale	float	否	比例：1 方块 = ? 米，0.5-8，默认 1（1:1）
level_h	int	否	每层楼多少米，2-5，默认 3
format	string	否	bdx（默认，支持合并）/ mcstructure
merge	int	否	1（默认）= 整片合并成一个 map.bdx，导入即用、无需拼合；0 = 按块拆成多个文件（附拼合偏移表）
tile_m	float	否	分块模式的每块边长（米），120-480，默认 240；块数超 64 时自动放大

响应示例

（二进制）application/zip
【merge=1】map.bdx（整片已拼好，直接导入）+ 说明.txt
【merge=0】tile_0_0.bdx … 每块一个文件 + 说明.txt（含拼合偏移表）

返回的是 ZIP 文件流而非 JSON，请用 fetch/XHR 以 blob 接收后触发下载。合并模式会先做容量校验（按预估方块数与服务器实际 memory_limit 双重判断），超限会明确提示改用分块或调大 scale；实测 1146×89×1146（457 万方块）峰值内存约 560MB、耗时约 2 分钟、产物 0.8MB。生成规则与 geo_builder 完全一致（同一套地表分类 / 建筑材质 / 门窗屋顶逻辑）。

POST /api/textkit.php

文本工具箱

69 种文本处理工具（大小写、编码解码、哈希、进制、繁简、时间戳等）

参数	类型	必填	说明
tool	string	是	工具名，如 beautify / t2s / codec / hash_md5
input	string	是	输入文本
params	string	否	JSON 字符串形式的附加参数
action	string	否	run（默认）

响应示例

{
  "success": true,
  "tool": "upper",
  "result": "处理结果文本"
}

工具清单与站内「辅助工具箱」页面一致，共 69 个。

POST /api/ai_builder.php

AI 建筑生成（流式）

自然语言生成建筑代码，流式转发上游大模型输出；支持改用你自己的 OpenAI 兼容 API

参数	类型	必填	说明
prompt	string	是	建筑描述（JSON body）
history	array	否	对话历史
api_base	string	否	自定义 API 地址（OpenAI 兼容，写到版本号，如 https://xxx/v1）。填了就不再走站内线路
api_key	string	否	自定义密钥，仅用于本次请求，不落库不写日志；本地模型可留空
model	string	否	自定义模型名，与 api_base 同时提供才生效

响应示例

SSE 流：
  data: {"choices":[{"delta":{"content":"…"}}]}     上游文本增量
  data: {"type":"code","code":"// VoxelBuilder JS","model":"x","custom":true}
  data: {"error":"…"}                                顶层错误（线路不可用 / 自定义 API 报错）
  data: [DONE]

填了 api_base + model 就**只走自定义线路**，不做任何回退（回退到站内密钥会在用户不知情时扣站长额度）。自定义地址经过校验：只允许 http/https，并默认拦截内网/保留地址防 SSRF；本站要接内网模型（ollama/vLLM）时把 api/lib/ai_proxy.php 的 AI_PROXY_ALLOW_PRIVATE 改成 true。密钥只保存在用户浏览器 localStorage，随请求转发，服务端不持久化。

POST /api/ai_models.php

拉取自定义 API 的模型列表

中转请求 {api_base}/models（OpenAI 兼容标准接口），避免浏览器直连被 CORS 挡住、也避免前端直接携带密钥

参数	类型	必填	说明
api_base	string	是	OpenAI 兼容 API 地址，如 https://platform.xiaozhouweb.com/v1
api_key	string	否	密钥，可留空

响应示例

{
  "success": true,
  "models": ["deepseek-v4-flash-max", "GLM-5.3-Flash"],
  "count": 2
}

兼容 {data:[{id}]} / {models:[…]} / 纯数组三种返回结构。地址校验同 ai_builder.php（默认拦截内网 / 保留地址）。密钥只用于本次请求，不写日志。

站点接口

站点自身使用的接口

POST /api/feedback.php

问题反馈

提交留言，写入站点反馈记录并邮件通知站长

参数	类型	必填	说明
content	string	是	反馈内容（5-2000 字）
contact	string	否	联系方式，最长 100 字
type	string	否	反馈类型，默认「其他」

响应示例

{ "success": true }

关于 api/app/ 与 api/fast/

这两组是 APP 端专用接口（登录态 / 会话校验），与站点账号体系绑定，不对外开放，请勿直接调用。

API 开放接口

查询类

格式转换

音乐处理

图片与动画

预览与文本

站点接口