GET /minecraft/model

访问类别：匿名 API，可携带 Token 使用独立额度

请求参数

playerquery必填: Java 版玩家名或 UUID，UUID 可以包含连字符; string · Java 版玩家名或 UUID，UUID 可以包含连字符 · 格式：^(?:[A-Za-z0-9_]{1,16}|[a-fA-F0-9]{32}|[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$
overlayquery: 是否显示皮肤外层; string · 是否显示皮肤外层 · 默认值："true" · 可选：true、false
viewquery: 头部、半身或全身；头部忽略披风设置; string · 头部、半身或全身；头部忽略披风设置 · 默认值："body" · 可选：head、bust、body
posequery: 站立、行走、奔跑、右手挥手或双腿前伸坐姿；省略时为 standing，与 rotations 互斥; string · 站立、行走、奔跑、右手挥手或双腿前伸坐姿；省略时为 standing，与 rotations 互斥 · 可选：standing、walking、running、waving、sitting
rotationsquery: 部位旋转 JSON，与显式 pose 互斥。支持 head、cape、leftArm、rightArm、leftLeg、rightLeg；每个部位的 x/y/z 为 −180～180 度数值，可含小数。省略的部位和轴采用 standing 角度（披风 x=-10，其余为 0）。左右以角色自身为准；X 向角色左侧、Y 向下、Z 向前，按固定模型轴依次旋转 X、Y、Z，正角遵循右手规则。头部绕颈部中心旋转，四肢及披风绕连接点旋转。; string · 部位旋转 JSON，与显式 pose 互斥。支持 head、cape、leftArm、rightArm、leftLeg、rightLeg；每个部位的 x/y/z 为 −180～180 度数值，可含小数。省略的部位和轴采用 standing 角度（披风 x=-10，其余为 0）。左右以角色自身为准；X 向角色左侧、Y 向下、Z 向前，按固定模型轴依次旋转 X、Y、Z，正角遵循右手规则。头部绕颈部中心旋转，四肢及披风绕连接点旋转。 · 最长：4096 字符
capequery: 显示玩家披风；没有披风时返回 MC_CAPE_NOT_FOUND; string · 显示玩家披风；没有披风时返回 MC_CAPE_NOT_FOUND · 默认值："false" · 可选：true、false

响应

200 包含几何、部位节点、材质和内嵌 PNG 纹理的 GLB 模型；缓存 300 秒

model/gltf-binary

{
  "type": "string",
  "format": "binary"
}

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"
  ]
}

404 请求校验或执行失败

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"
  ]
}

503 请求校验或执行失败

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/model?player=Dinnerbone&overlay=true&view=body&pose=standing&cape=false'

HTTP 200
content-type: model/gltf-binary
content-length: 27420
content-disposition: attachment; filename="Dinnerbone-body-standing.glb"
cache-control: public, max-age=300

(二进制 27420 字节)

错误示例

curl --silent --show-error -H 'User-Agent: simpleWebUtils-example/1.1.0' -H 'Accept: application/json' "$BASE_URL"'/minecraft/model?player=invalid+value&overlay=true&view=body&pose=standing&cape=false'

HTTP 400
content-type: application/json
content-encoding: gzip
cache-control: no-store

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "参数无效",
    "issues": [
      {
        "location": "query",
        "field": "player",
        "code": "invalid_format",
        "message": "格式要求：/^(?:[A-Za-z0-9_]{1,16}|[a-fA-F0-9]{32}|[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$/"
      }
    ]
  }
}

导出 Minecraft Java 三维 GLB 模型

请求参数

响应

响应示例

成功响应

错误示例

在线调试

响应