使用 HTTP API

从任意 HTTP 客户端驱动 Beam Bench。与 CLI 执行相同操作，便于集成。

Beam Bench 的 HTTP / WebSocket API 与 CLI 使用的是同一接口。如果你的使用场景需要在非 CLI 环境中使用 Beam Bench，例如 Web 应用、集成服务器或移动应用，请直接使用 HTTP API。

所需内容

已安装 Beam Bench。
在编辑 → 设置 → 常规中启用本地 API。默认关闭。
HTTP 客户端（curl、你的语言的 HTTP 库、Postman 等）。

验证 API 已启用

当前版本的默认设置经过有意锁定：

本地 API：关闭。
API 端口：5900。
允许网络设备连接：关闭。保持关闭时，服务器只接受来自此计算机的连接。

打开桌面应用，进入编辑 → 设置 → 常规，然后开启本地 API。对于在同一台计算机上运行的脚本，请保持允许网络设备连接关闭。设置会立即生效。

在共享 Wi-Fi 上绑定到网络前，请阅读 HTTP API 页面。API 没有身份验证，并且可以移动机器和触发激光。

基础 URL

http://localhost:5900/api/v1

（当允许网络设备连接开启时，也可以使用机器的局域网 IP 替代 localhost。）

步骤

1. 验证 API 正常运行

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

返回功能架构。（如果更改了端口，请将 5900 替换为已配置的端口。）

2. 检查状态

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

3. 打开项目

curl -s -X POST http://localhost:5900/api/v1/projects/open \
  -H 'Content-Type: application/json' \
  -d '{"path":"/abs/path/to/file.lzrproj"}'

4. 通过正在运行的服务器渲染设计

curl -s -X POST http://localhost:5900/api/v1/design/render \
  -H 'Content-Type: application/json' \
  -d '{"format":"png","pixels_per_mm":4,"output_path":"/tmp/out.png"}'

5. 获取相机状态

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

6. 通过应用前端渲染相机叠加层

curl -s -X POST http://localhost:5900/api/v1/camera/overlay/render \
  -H 'Content-Type: application/json' \
  -d '{"output_path":"/tmp/overlay.png","view":"fit","keep":true}'

可用的端点组

完整接口请参阅API 参考部分（内容填充后）。主要分组如下：

/agent，功能、状态、指南。
/camera，设备、状态、捕获、叠加层（显示、变换、渲染）、校准、对齐。
/design，描述、渲染、事务。
/projects，打开、保存、关闭、图层、对象、撤销/重做、导入。
/export，svg、dxf、pdf、eps、ai。

安全性

API 服务器没有身份验证，默认信任所在网络。

仅绑定 localhost 可将暴露范围限制在本地计算机。
网络绑定是单独的主动选择，会向同一局域网中的任何人开放 API。仅在受信任的网络上启用。

验证是否成功

curl agent/capabilities返回 JSON。
渲染调用会生成请求的文件。