使用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。
渲染调用会生成请求的文档。