HTTP API
Управляйте Beam Bench из любого HTTP-клиента. Используется тот же интерфейс, с которым работает CLI.
HTTP API является интерфейсом интеграции Beam Bench. Большинство команд CLI и внешних клиентов используют эти маршруты. Настольный интерфейс обращается к общей службе через Tauri IPC и не требует HTTP-сервера для обычной работы. Если вам нужно использовать Beam Bench в среде без CLI, например в веб-приложении, сервере интеграции, мобильном приложении или собственных инструментах, обращайтесь к API напрямую.
API поставляется вместе с настольным приложением и работает внутри его процесса. Отдельную службу устанавливать не нужно.
Значения по умолчанию и безопасность
В текущей сборке локальный API-сервер поставляется с такими настройками:
- Локальный API: выключен.
- Порт API: 5900.
- Разрешить сетевым устройствам подключаться: выключено. Когда API включен, он привязывается к
127.0.0.1и принимает подключения только с этого компьютера.
API не принимает подключения, пока вы явно не включите его. Разрешение сетевого доступа требует отдельного явного включения, поскольку API не использует аутентификацию и содержит операции, способные перемещать станок и включать лазер.
Чтобы использовать API, измените его настройки в разделе Настройки → Общие:
- Откройте настольное приложение.
- Изменить → Настройки → Общие.
- Включите Локальный API.
- Оставьте параметр Разрешить сетевым устройствам подключаться выключенным, если подключение не требуется с другого доверенного устройства.
Изменения вступают в силу немедленно, перезапуск не требуется.
Базовый 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": "invalid_input",
"message": "Human-readable summary of what went wrong.",
"details": { "...optional structured context..." }
}
}error.code принимает одно из значений:
| Код | HTTP | Значение |
|---|---|---|
not_found | 404 | Запрошенный ресурс не существует. |
invalid_input | 400 | Тело запроса или параметры имеют неверный формат либо были отклонены. |
invalid_state | 412 | Приложение находится не в том состоянии, в котором эта операция имеет смысл, например проект не открыт. |
busy | 409 | Уже выполняется конфликтующая операция. |
conflict | 409 | Другой процесс изменил ресурс после последнего чтения. |
stale_revision | 412 | Ваш токен ревизии отстает от текущего. Снова прочитайте данные и повторите попытку. |
machine_io | 502 | Не удалось установить соединение со станком: отключение, тайм-аут или ошибка транспорта. |
persistence | 500 | Не удалось записать данные на диск или прочитать их. |
internal | 500 | Непредвиденная ошибка сервера. Сообщите об этой ошибке как об ошибке программы. |
Ошибки, требующие подтверждения
Небольшой набор операций может перемещать станок или включать лазер. Для таких конечных точек в теле запроса требуется явный флаг подтверждения. Если он отсутствует, 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.
Параллельное редактирование проекта
Транзакции дизайна сравнивают зафиксированное состояние проекта во время фиксации изменений. Параллельное редактирование, переключение проекта или его закрытие может вернуть stale_revision. Обновите состояние и заново оцените изменение перед повторной попыткой. Не воспроизводите вслепую старый снимок проекта поверх более новой работы.
Группы конечных точек
| Путь | Назначение |
|---|---|
/api/v1/app | Информация об уровне приложения: версия, время работы, возможности. |
/api/v1/agent | Схема возможностей агента, снимок состояния и руководство по работе. |
/api/v1/projects | Открытие, сохранение и закрытие. Слои, объекты, отмена и повтор. |
/api/v1/projects/import | Импорт файлов LightBurn, SVG, DXF, PDF, AI, EPS и растровых файлов. Отдельный маршрут обрабатывает ограниченный импорт геометрии G-code. |
/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 без изменения версии.
Связанные материалы
- Руководство по использованию HTTP API: введение в формате учебника с рабочими примерами.
- Как CLI и приложение совместно используют состояние: модель согласованности, лежащая в основе этих конечных точек.
- Настройки → Общие: включение API и выбор порта.