Beam Bench文档

HTTP API

通过任意HTTP客户端驱动Beam Bench。与CLI通信的同一接口。

HTTP API是Beam Bench的集成接口。大多数CLI命令和外部客户端使用这些路由。桌面前端通过Tauri IPC调用共享服务，正常使用不需要HTTP服务器。如果你的用例需要在非CLI环境中使用Beam Bench（Web应用、集成服务器、移动应用或自有工具），请直接使用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没有令牌、密钥或登录功能。

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

请求格式

所有POST/PATCH/PUT请求体都使用JSON：

Content-Type: application/json

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

响应封装

成功响应直接返回资源体，不使用封装：

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

错误返回统一的封装：

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

error.code的取值包括：

代码HTTP含义
not_found404请求的资源不存在。
invalid_input400请求体或参数格式错误，或被拒绝。
invalid_state412应用当前不处于适合执行此操作的状态（例如没有打开项目）。
busy409已有冲突操作正在进行。
conflict409自上次读取后，另一位写入者更改了该资源。
stale_revision412你的修订令牌落后于当前令牌。请重新读取后重试。
machine_io502机器连接失败（断开、超时或传输错误）。
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。

并发项目编辑

设计事务会在提交时比较其捕获的项目。并发编辑、切换项目或关闭项目可能返回stale_revision。请刷新状态，并在重试前重新评估更改。不要盲目地将较旧的项目快照重新覆盖到较新的工作上。

端点组

路径覆盖内容
/api/v1/app应用级信息：版本、运行时间和功能。
/api/v1/agent代理功能架构、状态快照和操作指南。
/api/v1/projects打开、保存和关闭项目。图层、对象、撤销和重做。
/api/v1/projects/import导入LightBurn、SVG、DXF、PDF、AI、EPS和栅格文件。专用路由处理有限的G-code几何导入。
/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身份验证请求格式响应封装需要确认的错误并发项目编辑端点组发现实时接口版本控制相关内容