Minecraft
查询 Minecraft Java 状态与 MOTD
GET
/minecraft/java公开访问
访问类别：匿名 API，可携带 Token 使用独立额度
请求参数
hostquery必填- string · 最短：1 字符 · 最长：253 字符
portquery- 显式填写时使用该端口；省略时对域名查询 SRV，无 SRV 时使用 25565
- integer · 显式填写时使用该端口；省略时对域名查询 SRV，无 SRV 时使用 25565 · 最小值：1 · 最大值：65535
响应
200 服务器状态；latencyMs 包括 SRV、地址解析、TCP 连接与状态响应
application/json
{
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"address": {
"type": "string"
},
"resolved": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"srv": {
"type": [
"object",
"null"
],
"properties": {
"target": {
"type": "string"
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"priority": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"weight": {
"type": "integer",
"minimum": 0,
"maximum": 65535
}
},
"required": [
"target",
"port",
"priority",
"weight"
]
}
},
"required": [
"host",
"port",
"srv"
]
},
"version": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"protocol": {
"type": "integer"
}
},
"required": [
"name",
"protocol"
]
},
"players": {
"type": "object",
"properties": {
"online": {
"type": "integer",
"minimum": 0
},
"max": {
"type": "integer",
"minimum": 0
},
"sample": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"name",
"id"
]
}
}
},
"required": [
"online",
"max",
"sample"
]
},
"motd": {},
"motdText": {
"type": "string"
},
"motdFormatted": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"color": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underlined": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"obfuscated": {
"type": "boolean"
}
},
"required": [
"text",
"color",
"bold",
"italic",
"underlined",
"strikethrough",
"obfuscated"
]
}
},
"favicon": {
"type": [
"string",
"null"
]
},
"rawStatus": {
"type": "object",
"additionalProperties": true,
"description": "服务器返回的完整状态 JSON，保留嵌套对象中的扩展字段。"
},
"extensions": {
"type": "object",
"additionalProperties": true,
"description": "除 version、players、description、favicon 外的全部原始顶层字段，包含 Forge、其他服务端和自定义元数据。"
},
"modLoaders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"source": {
"type": "string"
},
"encoding": {
"type": "string",
"enum": [
"json",
"optimized"
]
},
"fmlNetworkVersion": {
"type": [
"integer",
"null"
]
},
"truncated": {
"type": [
"boolean",
"null"
]
},
"mods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"marker": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"version",
"marker"
]
}
},
"channels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"version",
"required"
]
}
}
},
"required": [
"type",
"source",
"encoding",
"fmlNetworkVersion",
"truncated",
"mods",
"channels"
]
},
"description": "从 modinfo 和 forgeData 整理的模组及通道信息；marker 为兼容性标记；truncated 为 null 表示服务器未声明列表完整性。"
},
"latencyMs": {
"type": "integer",
"minimum": 0
},
"timings": {
"type": "object",
"properties": {
"dnsMs": {
"type": "integer",
"minimum": 0
},
"connectMs": {
"type": "integer",
"minimum": 0
},
"statusMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"dnsMs",
"connectMs",
"statusMs"
]
}
},
"required": [
"host",
"port",
"address",
"resolved",
"version",
"players",
"motdText",
"motdFormatted",
"favicon",
"rawStatus",
"extensions",
"modLoaders",
"latencyMs",
"timings"
],
"description": "原始 MOTD、纯文本与格式片段；favicon 为经过校验的 64×64 PNG data URL；players.sample 为服务器提供的样本，缺少时为 null。port 保留请求端口（省略时 25565），resolved 表示实际连接目标。timings 各阶段之和等于 latencyMs，均由 Worker 测量。"
}400 请求校验或执行失败
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}401 凭据无效、停用、过期或缺少所需 Token
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}403 需要管理员 Token
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}413 请求体过大
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}415 请求内容类型无效
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}429 请求过于频繁，Retry-After 为建议等待秒数；匿名额度及认证保护在各 Cloudflare 地点近似计数，Token 业务额度使用 D1 原子计数
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}500 内部执行失败
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}502 请求校验或执行失败
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}504 请求校验或执行失败
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "string",
"enum": [
"body",
"query",
"path",
"header"
]
},
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"location",
"field",
"code",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}响应示例
运行命令前，将环境变量 BASE_URL 设置为站点地址。
成功响应
curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/1.1.0' -H 'Accept: application/json' "$BASE_URL"'/minecraft/java?host=mc.hypixel.net&port=25565'
HTTP 200
content-type: application/json
content-encoding: gzip
cache-control: public, max-age=30
{
"host": "mc.hypixel.net",
"port": 25565,
"address": "172.65.197.160",
"resolved": {
"host": "mc.hypixel.net",
"port": 25565,
"srv": null
},
"version": {
"name": "Requires MC 1.8 / 1.21",
"protocol": 47
},
"players": {
"online": 19405,
"max": 200000,
"sample": []
},
"motd": "§f §aHypixel Network §c[1.8/26.3]\n§f §6§lSKYBLOCK §e§lGHOST VISITORS",
"motdText": " Hypixel Network [1.8/26.3]\n SKYBLOCK GHOST VISITORS",
"motdFormatted": [
{
"color": "#ffffff",
"bold": false,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": " "
},
{
"color": "#55ff55",
"bold": false,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": "Hypixel Network "
},
{
"color": "#ff5555",
"bold": false,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": "[1.8/26.3]"
},
{
"color": "#ff5555",
"bold": false,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": "\n"
},
{
"color": "#ffffff",
"bold": false,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": " "
},
{
"color": "#ffaa00",
"bold": true,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": "SKYBLOCK "
},
{
"color": "#ffff55",
"bold": true,
"italic": false,
"underlined": false,
"strikethrough": false,
"obfuscated": false,
"text": "GHOST VISITORS"
}
],
"rawStatus": {
"version": {
"name": "Requires MC 1.8 / 1.21",
"protocol": 47
},
"players": {
"max": 200000,
"online": 19405,
"sample": []
},
"description": "§f §aHypixel Network §c[1.8/26.3]\n§f §6§lSKYBLOCK §e§lGHOST VISITORS",
"favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAt0UlEQVR4XnV7B3hc1bX12Oq9Te+9d400TV2yLFndkiXZlm1Z7r3gChibEhwgiQ1JSELCgzyaqYFQQggvCQ/SXx6QkBgMJCZAIGBiMMbdWv86d2Qbkvf7+/Z3PTOambvXWXvttc+9IzObAr/oGh47Om/VCrSNLMD6q67Dpj3XY8boIqT6hpHuH0GaR/H/i9E7B7G2bun4hef/j2icPYLGwamQ/j+KrrExjKxYgokNK7D8stVYtW0N1l6+FusuxjqsZ2wQccV6bLzy/x+X7dqALbs2Yuvujdi+ZwO2X73xYmzjc3tu3IW9+7+EG75+A3bfuBvX778BE5vWomds8VmHM/pbWcfA8Hs/fPrRczd8fR9PbAL1fTzJvjn8o61o6BtCbXsPoi2dCDe2I9QwA8H6NgTrWhFINSOQbpHCz/9LkWy6GL5k479EQyYSDfzbRgTTTQjViWhEuP7z0YBwHSNdj0i6ARG+ngnx/4bMc6kGRNONqOb7o4wwPz+czPy/ur6ZIY58zIg1tKC2qRW1LTMQSrWgiTntvvF6/PDpByf7Fiz8TNY9tnDyznv2o2fOMGy+JMz+JIy+BDw1TbAE0zAHUtJzpqkQr4mQHovjv4R56jN0DL34e3+Kf5sJC8Mq/Z/v9fJz3LUoUxqRlVWEabJ8Rh6m81iYVwWNwQWbtRpWYxgWYwgqlQ1ypRXllWYo1XYUlNggk8mmogQyhQN6fp7BHoPelYDOw+/3iGMCWreIuPR/JV9r75+Nfd/cjdXb1kLWPm8hKbcV/lg9KlROKNQWVKnMKC7XorzKgAq5ERUKIyoZVQyFwiRFuYKvXQy+prJArnWgVO9CudEDtyMCl7NaAtUokvUKgARoSWjsYRQVVSCXCWczgfIqJTRGG9QGK/RmF8JN7ZixZDlmTCxHPUumfnAuWhYsxsylK9G7Zh06lq/C4NqNWLRxC8Y3b8PImo0YXLYG3kQLqtRmflccRk8tAamGwVMDk7sGRld1ZpG4AIFkC/rHRjGxfjlkrcNj2Lz7SgRq61FUpoeqygJVhRmqSguUPKqlyDxnr7QhoPCgRuWHvtwAeakWhbnFKMovg7LSCk2VA3a5AzGlC8uNEYwZwqhT2VFUWIb84nLIcyuQN72Qq65FVlEZk7bD4g2jfs48tDO59mUrMZPJ9Wy8DF1rNqB53gRaF
… 已截断，完整响应 33887 字符错误示例
curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/1.1.0' -H 'Accept: application/json' "$BASE_URL"'/minecraft/java?host=invalid+value&port=25565'
HTTP 400
content-type: application/json
content-encoding: gzip
cache-control: no-store
{
"error": {
"code": "INVALID_INPUT",
"message": "参数无效",
"issues": [
{
"location": "query",
"field": "host",
"code": "custom",
"message": "Invalid input"
}
]
}
}在线调试
调用示例
curl -X GET 'https://oit.sh/minecraft/java?host=mc.hypixel.net'
响应
等待发送请求
配置上方请求参数后点击「发送请求」查看实时响应
快捷键：Ctrl / ⌘ + Enter