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身份驗證請求格式響應封裝需要確認的錯誤端點分組發現即時介面版本管理相關內容