使用 HTTP API

透過任何 HTTP 用戶端控制 Beam Bench。與 CLI 執行相同操作，方便整合。

Beam Bench 的 HTTP / WebSocket API 與 CLI 使用的介面相同。如果你的使用情境需要在非 CLI 環境中使用 Beam Bench，例如網頁應用程式、整合伺服器或行動應用程式，請直接使用 HTTP API。

需要的項目

已安裝 Beam Bench。
在 編輯 → 設定 → 一般 中啟用 Local API。預設為關閉。
HTTP 用戶端（curl、你的程式語言 HTTP 函式庫、Postman 等）。

驗證 API 已啟用

目前版本的預設值刻意設為受限狀態：

Local API：關閉。
API Port：5900。
允許網路裝置連線：關閉。保持關閉時，伺服器只接受來自此電腦的連線。

開啟桌面應用程式，前往 編輯 → 設定 → 一般，然後開啟 Local API。在同一部電腦上執行指令碼時，請保持 允許網路裝置連線 關閉。設定會立即生效。

在共用 Wi-Fi 上繫結至網路前，請閱讀 HTTP API 頁面。API 沒有驗證機制，而且可以移動機器並發射雷射。

基底 URL

http://localhost:5900/api/v1

（當 允許網路裝置連線 開啟時，也可以使用機器的 LAN 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 可限制暴露範圍至本機。
網路繫結是個別的選擇性啟用項目，會讓同一 LAN 上的任何人都能存取 API。只有在可信任的網路上才啟用。

驗證是否成功

curl agent/capabilities 會回傳 JSON。
轉譯呼叫會產生所要求的檔案。