HTTP API

Ovládejte Beam Bench z libovolného HTTP klienta. Stejné rozhraní, které používá CLI.

HTTP API je integrační rozhraní pro Beam Bench. Většina příkazů CLI a externích klientů používá tyto trasy. Desktopový frontend volá sdílenou službu přes Tauri IPC a při běžném používání nepotřebuje HTTP server. Pokud potřebujete Beam Bench používat v prostředí bez CLI (webová aplikace, integrační server, mobilní aplikace nebo vlastní nástroje), použijte API přímo.

API je součástí desktopové aplikace a běží v rámci jejího procesu. Není třeba instalovat samostatnou službu.

Výchozí nastavení a zabezpečení

V aktuálním sestavení je místní API server dodáván s tímto nastavením:

Místní API: vypnuto.
Port API: 5900.
Povolit zařízení v síti: vypnuto. Když je API povoleno, naváže se na 127.0.0.1 a přijímá připojení pouze z tohoto počítače.

API nenaslouchá připojením, dokud jeho použití výslovně nepovolíte. Povolení síťového přístupu je samostatná volba, protože API nevyžaduje ověření a obsahuje operace, které mohou pohybovat strojem a aktivovat laser.

Chcete-li API používat, změňte jeho nastavení v Nastavení → Obecné:

Otevřete desktopovou aplikaci.
Úpravy → Nastavení → Obecné.
Zapněte Místní API.
Povolit zařízení v síti ponechte vypnuté, pokud se nemusí připojit jiné důvěryhodné zařízení.

Změny se projeví okamžitě, restart není potřeba.

Základní URL

http://<host>:5900/api/v1

<host> je localhost (nebo 127.0.0.1), když je Povolit zařízení v síti vypnuté. Když je zapnuté, je server dostupný na LAN IP adrese stroje z libovolného zařízení v síti.

Port lze nastavit v Nastavení → Obecné; výchozí hodnota je 5900.

Ověřování

Žádné. API nemá token, klíč ani přihlášení.

Při vazbě na localhost tvoří hranici model přístupu na úrovni operačního systému: s API může komunikovat jakýkoli proces na vašem počítači.
Při povolené síťové vazbě může s API komunikovat kdokoli ve stejné síti. Režim síťové vazby nepoužívejte v nedůvěryhodné Wi-Fi.

Formát požadavku

Všechna těla požadavků POST/PATCH/PUT jsou JSON:

Content-Type: application/json

Řetězce dotazů jsou ploché key=value. Segmenty cesty jsou obvyklým způsobem zakódované jako URL.

Obálka odpovědi

Úspěšné odpovědi vracejí přímo tělo prostředku bez obálky:

{
  "field": "value",
  "...": "..."
}

Chyby vracejí jednotnou obálku:

{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code je jedna z těchto hodnot:

Kód	HTTP	Význam
`not_found`	404	Požadovaný prostředek neexistuje.
`invalid_input`	400	Tělo požadavku nebo parametry byly chybně formátované či odmítnuté.
`invalid_state`	412	Aplikace není ve stavu, ve kterém tato operace dává smysl (například není otevřený žádný projekt).
`busy`	409	Probíhá již konfliktní operace.
`conflict`	409	Jiný zapisující proces změnil prostředek od vašeho posledního načtení.
`stale_revision`	412	Váš revizní token je pozadu za aktuálním tokenem. Znovu načtěte stav a opakujte pokus.
`machine_io`	502	Připojení ke stroji selhalo (odpojení, vypršení časového limitu, chyba přenosu).
`persistence`	500	Zápis nebo čtení disku selhalo.
`internal`	500	Neočekávaná chyba serveru. Nahlaste ji jako chybu.

Chyby vyžadující potvrzení

Malá skupina operací může pohybovat strojem nebo aktivovat laser. Tyto endpointy vyžadují v těle požadavku explicitní příznak potvrzení. Pokud chybí, API vrátí 428 Precondition Required:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Odešlete požadavek znovu s pojmenovaným příznakem nastaveným na true. Aktuálně se používají příznaky confirm_motion, confirm_laser_on, confirm_raw_gcode a confirm_air_assist.

Souběžné úpravy projektu

Transakce návrhu porovnávají zachycený projekt v okamžiku potvrzení. Souběžná úprava, přepnutí projektu nebo jeho zavření může vrátit stale_revision. Obnovte stav a před opakováním znovu posuďte změnu. Starší snímek projektu slepě nepřepisujte přes novější práci.

Skupiny endpointů

Cesta	Co pokrývá
`/api/v1/app`	Informace na úrovni aplikace: verze, doba běhu, schopnosti.
`/api/v1/agent`	Schéma schopností agenta, snímek stavu a provozní příručka.
`/api/v1/projects`	Otevření, uložení a zavření. Vrstvy, objekty, zpět a znovu.
`/api/v1/projects/import`	Import souborů LightBurn, SVG, DXF, PDF, AI, EPS a rastrových souborů. Vyhrazená trasa zpracovává omezený import geometrie G-code.
`/api/v1/export`	Vykreslení projektu do SVG, DXF, PDF, EPS a AI.
`/api/v1/design`	Popis aktuálního návrhu, vykreslení do PNG, použití transakčních úprav.
`/api/v1/preview`	Generování náhledů řezání a statistik.
`/api/v1/jobs`	Kontrola před spuštěním, spuštění, zkušební běh, pozastavení, pokračování, ohraničení, zastavení.
`/api/v1/machine`	Připojení, odpojení, stav, krokování, najetí do výchozí polohy.
`/api/v1/camera`	Zařízení, stav, snímání, překryv (zobrazení, transformace, vykreslení), kalibrace a zarovnání.
`/api/v1/console`	Odeslání nezpracovaného G-code. Čtení nedávného protokolu konzole.
`/api/v1/macros`	Výpis, uložení a spuštění uživatelských maker.
`/api/v1/materials`	Knihovna materiálů: předvolby indexované podle materiálu a tloušťky.
`/api/v1/profiles`	Profily stroje: vytvoření, výpis a použití.
`/api/v1/assets`	Přístup k prostředkům knihovny grafiky.
`/api/v1/vector`	Vektorové operace: převod, booleovské operace, seskupení a cesta.
`/api/v1/events`	Stream změn stavu a událostí stroje přes WebSocket.

Referenční stránky jednotlivých prostředků se stále připravují; mezitím nahlédněte do schématu schopností agenta.

Zjištění aktuálního rozhraní

Nejrychlejší způsob, jak zjistit, co nabízí vaše nainstalovaná verze:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Výsledkem je úplné schéma schopností včetně každého endpointu, jeho parametrů a tvaru odpovědi. Schéma je autoritativním popisem; tato stránka je jeho průvodcem.

Pro zjištění stavu:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Pro písemné vysvětlení ovládání aplikace:

curl -s http://localhost:5900/api/v1/agent/guide

Verze

Všechny trasy jsou pod /api/v1. Pokud dojde k nekompatibilním změnám, budou umístěny do /api/v2. Aditivní změny (nové endpointy, nová volitelná pole) se dodávají ve v1 bez zvýšení verze.

Související

Průvodce používáním HTTP API: úvod ve stylu výukového kurzu s praktickými příklady.
Jak CLI a aplikace sdílejí stav: model konzistence na pozadí těchto endpointů.
Nastavení → Obecné: místo, kde povolíte API a zvolíte port.

HTTP API

On this page