Beam Bench文档

HTTP API

从任意 HTTP 客户端驱动 Beam Bench。CLI 也使用同一套接口。

HTTP API是Beam Bench的集成接口。桌面应用、CLI和任何外部客户端都使用同一组路由。如果你的使用场景需要在非CLI环境（Web应用、集成服务器、移动应用或你自己的工具）中使用Beam Bench，请直接调用API。

API随桌面应用一同提供，并在进程内运行。无需安装单独的服务。

默认设置与安全性

在当前版本中，本地 API 服务器随附以下设置：

  • 本地 API：关闭。
  • API 端口：5900。
  • 允许网络设备：关闭。启用 API 后，它会绑定到 127.0.0.1，仅接受来自此计算机的连接。

在你主动选择启用之前，API不会监听连接。启用网络访问需要单独选择，因为API无需身份验证，并且包含可以移动机器和发射激光的操作。

要使用API，请在设置 → 常规中更改设置：

  1. 打开桌面应用。
  2. 编辑 → 设置 → 常规 。
  3. 打开 本地 API 。
  4. 除非必须让另一台受信任的设备连接，否则请保持 允许网络设备 关闭。

更改会立即生效，无需重启。

基础 URL

http://<host>:5900/api/v1

当 允许网络设备 关闭时，<host> 是 localhost（或 127.0.0.1 ）。启用后，网络中的任何设备都可以通过机器的局域网 IP访问服务器。

端口可在设置 → 常规中配置；5900为默认端口。

身份验证

无。API没有令牌、密钥或登录功能。

  • 绑定到 localhost 时，操作系统级访问模型就是边界：你机器上的任何进程都可以与API通信。
  • 启用网络绑定后，同一网络中的任何人都可以与API通信。请勿在不受信任的Wi-Fi上使用网络绑定模式。

请求格式

所有POST/PATCH/PUT请求正文均为JSON：

Content-Type: application/json

查询字符串采用扁平的key=value形式。路径段按常规进行URL编码。

响应封装

成功响应直接返回资源正文，不包含包装层：

{
  "field": "value",
  "...": "..."
}

错误响应返回统一封装：

{
  "error": {
    "code": "InvalidInput",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code 的取值包括：

代码HTTP含义
NotFound404请求的资源不存在。
InvalidInput400请求正文或参数格式错误，或被拒绝。
InvalidState412应用当前状态不适合执行此操作（例如未打开项目）。
Busy409冲突操作已在进行中。
Conflict409自你上次读取后，其他写入者已更改该资源。
StaleRevision412你的修订令牌落后于当前令牌。请重新读取后重试。
MachineIo502机器连接失败（断开连接、超时或传输错误）。
Persistence500磁盘写入或读取失败。
Internal500服务器发生意外错误。请将其作为缺陷报告。

需要确认的错误

少数操作可以移动机器或发射激光。这些端点要求在请求正文中明确提供确认标志。若缺少该标志，API会返回 428 Precondition Required：

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

请将指定标志设为 true 后重新发送请求。当前使用的标志包括 confirm_motion 、 confirm_laser_on 、 confirm_raw_gcode 和 confirm_air_assist 。

端点分组

路径覆盖内容
/api/v1/app应用级信息：版本、运行时间、功能。
/api/v1/agent代理能力架构、状态快照和操作指南。
/api/v1/projects打开、保存、关闭项目；图层、对象、撤销/重做。
/api/v1/projects/import将 SVG、DXF、PDF、AI 和栅格图像导入项目。
/api/v1/export将项目渲染为 SVG、DXF、PDF、EPS、AI。
/api/v1/design描述当前设计、渲染为 PNG、应用事务性编辑。
/api/v1/preview生成切割预览和统计信息。
/api/v1/jobs预检、运行、空运行、暂停、恢复、走框、停止。
/api/v1/machine连接、断开、状态、点动、回零。
/api/v1/camera设备、状态、采集、叠加层（显示、变换、渲染）、校准、对齐。
/api/v1/console发送原始 G-code。读取最近的控制台日志。
/api/v1/macros列出、保存和运行用户宏。
/api/v1/materials材料库：按材料和厚度索引的预设。
/api/v1/profiles机器配置文档：创建、列出、应用。
/api/v1/assets图稿库资源访问。
/api/v1/vector矢量操作：转换、布尔运算、分组、路径。
/api/v1/events状态变化和机器事件的 WebSocket 流。

各资源的参考页面仍在完善中；在此期间请参阅代理能力架构。

发现实时接口

查看已安装版本提供的接口，最快的方法是：

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

这会返回完整的能力架构，包括每个端点、其参数和响应结构。该架构是权威说明；本页面只是对它的介绍。

查看状态详情：

curl -s http://localhost:5900/api/v1/agent/state | jq .

如需了解如何操作应用的文字说明：

curl -s http://localhost:5900/api/v1/agent/guide

版本管理

所有路由均位于 /api/v1 下。发生破坯性更改时，将在 /api/v2 中提供。增量更改（新端点、新可选字段）会在不提升版本号的情况下随 v1 发布。

相关内容

坐标系

工作区、作业、绝对坐标、屏幕。每个控件使用哪种坐标，以及它们如何转换。

发行说明

Beam Bench 各版本的变更内容。

On this page

默认设置与安全性基础 URL身份验证请求格式响应封装需要确认的错误端点分组发现实时接口版本管理相关内容