Mars Printer Hub Wiki

Appearance

开放接口 ​

本页按接口顺序说明开放接口的接入方式、请求参数、实际请求示例和返回结构。

基础信息 ​

官方服务地址：

http
https://hcgl.top

私有部署说明

如果你使用的是私有部署版本，请将文档中的 https://hcgl.top 替换为你自己的服务地址。

开放接口统一返回结构如下：

json
{
  "code": 0,
  "data": {},
  "message": "ok"
}

API Key 获取与使用 ​

开放接口通过 API Key 鉴权，不使用网页登录态。

获取方式：

  1. 登录系统
  2. 打开个人中心
  3. 进入 API Key 管理
  4. 创建或重置 API Key
  5. 复制创建时返回的明文 key

使用方式：

  • 在请求头中传入 X-API-Key
  • 每个用户当前只有一把 key
  • 重置后，旧 key 会立即失效
  • 禁用后，当前 key 无法继续调用需要鉴权的开放接口

请求头示例：

http
X-API-Key: mph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

注意

API Key 只在创建或重置时展示一次，请妥善保存。

接口列表 ​

当前开放接口定位是外部系统只读查询。

接口方法是否需要 X-API-Key说明
/api/open/pingGET否开放接口健康检查
/api/open/whoamiGET是查询当前 Open API 调用身份
/api/open/device/{deviceId}GET是查询设备信息

1. 健康检查 ​

用于确认开放接口服务是否可访问。

请求地址 ​

http
GET https://hcgl.top/api/open/ping

鉴权 ​

不需要传 X-API-Key。

实际请求示例 ​

GET/api/open/ping
请求地址https://hcgl.top/api/open/ping
bash
curl -X GET 'https://hcgl.top/api/open/ping'

返回示例 ​

json
{
  "code": 0,
  "data": "pong",
  "message": "ok"
}

2. 查询当前调用身份 ​

用于验证当前 API Key 是否有效，并返回后端识别到的用户 ID 和 API Key ID。

请求地址 ​

http
GET https://hcgl.top/api/open/whoami

请求头 ​

名称必填说明
X-API-Key是当前用户的开放接口凭证

实际请求示例 ​

GET/api/open/whoami
请求地址https://hcgl.top/api/open/whoami
bash
curl -X GET \
  'https://hcgl.top/api/open/whoami' \
  -H 'X-API-Key: 这里替换成你的apikey'

返回示例 ​

json
{
  "code": 0,
  "data": {
    "userId": "1",
    "apiKeyId": "10"
  },
  "message": "ok"
}

data 字段说明 ​

字段类型说明
userIdstring当前 API Key 绑定的用户 ID
apiKeyIdstring当前 API Key 的记录 ID

3. 查询设备信息 ​

用于查询当前用户名下指定打印机的开放设备信息。

请求地址 ​

http
GET https://hcgl.top/api/open/device/{deviceId}

路径参数 ​

参数类型必填说明
deviceIdstring是打印机设备 ID

请求头 ​

名称必填说明
X-API-Key是当前用户的开放接口凭证

实际请求示例 ​

GET/api/open/device/{deviceId}
请求地址https://hcgl.top/api/open/device/{deviceId}
bash
curl -X GET \
  'https://hcgl.top/api/open/device/DEVICE_ID' \
  -H 'X-API-Key: 这里替换成你的apikey'

返回示例 ​

json
{
  "code": 0,
  "data": {
    "name": "客厅 P1S",
    "deviceId": "DEVICE_ID",
    "model": "P1S",
    "printStatus": "RUNNING",
    "printProgress": 42,
    "taskImage": "https://example.com/task-cover.png",
    "remainingTime": 126,
    "chamberLight": "on",
    "chamberLight2": "off",
    "workLight": "on",
    "bedTemp": 60,
    "chamberTemp": 35,
    "nozzleTemp": 220,
    "activeNozzle": "single",
    "targetNozzleTemp": 220,
    "leftNozzleTemp": null,
    "leftTargetNozzleTemp": null,
    "rightNozzleTemp": null,
    "rightTargetNozzleTemp": null,
    "layerNum": 88,
    "totalLayerNum": 210,
    "trayType": "PLA",
    "hmsErrors": [
      {
        "code": "HMS_0300_0100_0001_0001",
        "message": "热床温控异常，加热器可能短路。",
        "severity": "fatal",
        "module": "mc"
      }
    ]
  },
  "message": "ok"
}

data 字段说明 ​

字段类型说明
namestring打印机名称
deviceIdstring设备 ID
modelstring打印机型号，枚举见下方
printStatusstring当前打印状态，枚举见下方
printProgressnumber当前打印进度，范围 0-100
taskImagestring当前任务封面图地址，可能为空
remainingTimenumber预计剩余打印时间，单位分钟
chamberLightstring主打印腔灯状态，常见值为 on / off
chamberLight2string第二路打印腔灯状态，常见值为 on / off
workLightstring工作灯状态，常见值为 on / off
bedTempnumber当前热床温度
chamberTempnumber当前仓温
nozzleTempnumber活动喷嘴当前温度，单位摄氏度
activeNozzlestring活动喷嘴，可能值为 single / left / right
targetNozzleTempnumber活动喷嘴目标温度，单位摄氏度
leftNozzleTempnumber左喷嘴当前温度，双喷嘴设备可能返回
leftTargetNozzleTempnumber左喷嘴目标温度，双喷嘴设备可能返回
rightNozzleTempnumber右喷嘴当前温度，双喷嘴设备可能返回
rightTargetNozzleTempnumber右喷嘴目标温度，双喷嘴设备可能返回
layerNumnumber当前层数
totalLayerNumnumber总层数
trayTypestring当前使用中的耗材类型，枚举见下方
hmsErrorsarray当前设备 HMS 错误列表，只包含可展示字段

喷嘴温度说明

单喷嘴设备通常返回 activeNozzle: "single"，并通过 nozzleTemp / targetNozzleTemp 表示当前喷嘴温度。

双喷嘴设备会同时返回左右喷嘴温度字段，并通过 activeNozzle 标识当前活动喷嘴；未上报的喷嘴温度字段可能为空。

hmsErrors 字段说明 ​

hmsErrors 与系统内设备详情接口 GET /api/device/{deviceId}/complete 的 HMS 错误展示结构一致。后端会根据设备上报的 HMS 信息和打印机型号解析错误码，只返回可展示的错误项。

当设备当前没有可展示 HMS 错误时，该字段通常为空数组。

字段类型说明
codestring标准 HMS 错误码，例如 HMS_0300_0100_0001_0001
messagestring中文错误描述
severitystring严重级别，可能值为 fatal / serious / common / info / unknown
modulestring错误模块，可能值为 mainboard / xcam / ams / toolhead / mc / unknown

权限校验说明 ​

该接口会同时校验：

  • API Key 对应的用户
  • 设备缓存归属
  • 数据库中的设备归属

如果设备不属于当前 API Key 用户，或缓存归属与数据库归属不一致，请求会直接返回错误，不继续处理。

printStatus 枚举 ​

printStatus 来自设备状态中的 gcode_state，当前项目中使用的枚举值如下：

值含义
FAILED失败
FINISH完成
IDLE空闲
OFFLINE离线
PREPARE准备中
RUNNING打印中
PAUSE暂停
SLICING切片中
INIT初始化

说明

不同设备型号或不同阶段上报的状态可能不完全一致，但当前系统内部已明确使用并兼容以上值。

model 枚举 ​

model 返回的是系统映射后的型号文本，当前项目中已定义的型号如下：

返回值底层设备型号值
X1CBL-P001
P1PC11
P1SC12
X1EC13
A1MININ1
A1N2S
X2DN6-V2
P2SN7-V2
H2CO1C2-V2
H2DO1D
H2SO1S

说明

如果后端收到未在映射表中的设备型号，接口会直接返回原始型号值，而不是上表中的文本。

trayType 枚举 ​

trayType 表示当前使用中的耗材类型，当前可能的值包括：

值值值值
ABSABS-GFASAASA-AERO
ASA-CFBVOHEVAHIPS
PAPA-CFPA-GFPA6-CF
PCPCTGPEPE-CF
PET-CFPETGPETG-CFPHA
PLAPLA-AEROPLA-CFPP
PP-CFPP-GFPPA-CFPPA-GF
PPSPPS-CFPVATPU
TPU-AMS

说明

trayType 由设备当前激活的料盘信息解析得到；当设备未上报耗材信息或当前槽位无法识别时，该字段可能为空。

常见错误 ​

场景说明
未传 X-API-Key请求未通过开放接口鉴权
API Key 无效或已禁用无法识别当前调用用户
deviceId 不存在目标设备不存在
当前用户无权访问该设备设备不属于当前 API Key 用户
设备归属校验不一致Redis 缓存归属与数据库归属不一致

错误返回示例 ​

接口错误时同样会返回统一响应结构，通常格式如下：

json
{
  "code": 40101,
  "data": null,
  "message": "无权访问该设备"
}

常见错误示例 ​

未传 X-API-Key 或身份缺失：

json
{
  "code": 40100,
  "data": null,
  "message": "Open API 调用身份缺失"
}

API Key 无效：

json
{
  "code": 40100,
  "data": null,
  "message": "API Key 无效"
}

API Key 已禁用：

json
{
  "code": 40100,
  "data": null,
  "message": "API Key 已禁用"
}

无权访问该设备：

json
{
  "code": 40101,
  "data": null,
  "message": "无权访问该设备"
}

设备不存在：

json
{
  "code": 40400,
  "data": null,
  "message": "设备不存在"
}

设备归属校验不一致：

json
{
  "code": 40101,
  "data": null,
  "message": "设备归属校验不一致"
}

调试建议 ​

  • 先调用 GET /api/open/ping 确认开放接口服务可访问
  • 再调用 GET /api/open/whoami 验证当前 API Key 是否生效
  • 最后调用 GET /api/open/device/{deviceId} 验证设备访问权限和设备数据
  • 如果出现归属不一致，请先检查设备绑定关系和缓存同步是否正常