HTTP APIの使用

任意のHTTPクライアントからBeam Benchを操作します。CLIと同じ操作に対応し、統合に適しています。

Beam BenchのHTTP / WebSocket APIは、CLIが使用するものと同じインターフェースです。Webアプリ、統合サーバー、モバイルアプリなど、CLI以外の環境でBeam Benchを使用する必要がある場合は、HTTP APIを直接使用してください。

必要なもの

Beam Benchがインストールされていること。
Edit → Settings → GeneralでLocal APIが有効になっていること。デフォルトでは無効です。
HTTPクライアント（curl、使用する言語のHTTPライブラリ、Postmanなど）。

APIが有効になっていることを確認する

現在のビルドのデフォルト設定は、意図的に厳しく制限されています。

Local API：オフ。
API Port：5900。
Allow network devices to connect：オフ。この設定がオフの間、サーバーはこのコンピューターからの接続のみを受け付けます。

デスクトップアプリを開き、Edit → Settings → Generalに移動して、Local APIをオンにします。同じコンピューターで実行するスクリプトの場合は、Allow network devices to connectをオフのままにしてください。設定はすぐに反映されます。

共有Wi-Fi上でネットワークにバインドする前に、HTTP APIページを読んでください。APIには認証機能がなく、マシンを移動させたりレーザーを発射したりできます。

ベースURL

http://localhost:5900/api/v1

（Allow network devices to connectがオンの場合は、localhostの代わりにマシンのLAN IPアドレスを使用することもできます。）

手順

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、capabilities、state、guide。
/camera、devices、state、capture、overlay（display、transform、render）、calibration、alignment。
/design、describe、render、transactions。
/projects、open、save、close、layers、objects、undo/redo、import。
/export、svg、dxf、pdf、eps、ai。

セキュリティ

APIサーバーには認証機能がありません。接続先のネットワークが信頼できることを前提としています。

localhostのみへのバインドにより、公開範囲をローカルマシンに限定できます。
ネットワークへのバインドは別途オプトインする必要があり、同じLAN上のすべてのユーザーにAPIを公開します。信頼できるネットワークでのみ有効にしてください。

動作を確認する

curl agent/capabilitiesがJSONを返すこと。
レンダリング呼び出しによって、指定したファイルが生成されること。