HTTP API 사용

모든 HTTP 클라이언트에서 Beam Bench를 제어하세요. CLI와 동일한 작업을 통합에 사용할 수 있습니다.

Beam Bench의 HTTP / WebSocket API는 CLI가 통신하는 것과 동일한 인터페이스입니다. 웹 앱, 통합 서버, 모바일 앱 등 CLI가 아닌 환경에서 Beam Bench가 필요한 사용 사례라면 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

(네트워크 장치의 연결 허용이 켜져 있는 경우 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, 기능, 상태, 가이드
/camera, 장치, 상태, 캡처, 오버레이(표시, 변환, 렌더링), 보정, 정렬
/design, 설명, 렌더링, 트랜잭션
/projects, 열기, 저장, 닫기, 레이어, 객체, 실행 취소 및 다시 실행, 가져오기
/export, svg, dxf, pdf, eps, ai

보안

API 서버에는 인증이 없습니다. 서버가 연결된 네트워크를 신뢰할 수 있다고 가정합니다.

localhost 전용 바인딩은 로컬 컴퓨터로 노출을 제한합니다.
네트워크 바인딩은 별도의 선택 동의이며, 동일한 LAN의 모든 사용자에게 API를 엽니다. 신뢰할 수 있는 네트워크에서만 활성화하세요.

작동 여부 확인

curl agent/capabilities가 JSON을 반환합니다.
렌더링 호출이 요청한 파일을 생성합니다.