HTTP API 사용하기

모든 HTTP 클라이언트에서 Beam Bench를 구동하세요. CLI와 동일한 작업을 지원하며 통합에 적합합니다.

Beam Bench의 HTTP / WebSocket API는 CLI가 사용하는 것과 동일한 인터페이스입니다. 웹 앱, 통합 서버, 모바일 앱 등 CLI가 아닌 환경에서 Beam Bench를 사용해야 하는 경우 HTTP API를 직접 사용하세요.

필요한 항목

Beam Bench가 설치되어 있어야 합니다.
Edit → Settings → General에서 Local API를 활성화합니다. 기본적으로 꺼져 있습니다.
HTTP 클라이언트(curl, 사용 중인 언어의 HTTP 라이브러리, Postman 등)가 필요합니다.

API 활성화 확인

현재 빌드의 기본값은 의도적으로 제한되어 있습니다.

Local API: 꺼짐.
API 포트: 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는 API 레퍼런스 섹션(내용이 채워진 경우)을 참조하세요. 주요 그룹은 다음과 같습니다.

/agent, 기능, 상태, 가이드.
/camera, 장치, 상태, 캡처, 오버레이(표시, 변환, 렌더링), 보정, 정렬.
/design, 설명, 렌더링, 트랜잭션.
/projects, 열기, 저장, 닫기, 레이어, 객체, 실행 취소/다시 실행, 가져오기.
/export, 형식: 형식: svg, dxf, pdf, eps, ai.

보안

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

로컬호스트 전용 바인딩은 로컬 컴퓨터로 노출을 제한합니다.
네트워크 바인딩은 별도로 활성화해야 하며, 같은 LAN의 모든 사용자에게 API를 개방합니다. 신뢰할 수 있는 네트워크에서만 활성화하세요.

작동 확인

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