Von einem Modell zu einer Zeichnung, über HTTP

• Ein Occlusia-Konto und ein API-Schlüssel, erstellt unter API-Schlüssel in Ihrem Konto. Bewahren Sie den Schlüssel in einer Umgebungsvariablen auf: Die Beispiele lesen OCCLUSIA_API_KEY.
• Ein Modell: eine .skp-Datei, gespeichert mit SketchUp 2021 oder neuer, eine .ifc-, .fbx- oder .occs-Datei, höchstens 512 MB.
• Ihr grafischer Standard als Konfiguration, aus Occlusia Studio exportiert mit Export › Configuration (.occc) — oder keiner, dann wird das Modell mit den Standardeinstellungen gezeichnet.
• Credits oder ein Konto des frühen Zugangs: Das Öffnen des Modells und jeder Export kosten Credits (API und MCP, Was es kostet).

1. 01

   Eine Sitzung öffnen

   POST /sessions startet eine eigene Engine, angemeldet an Ihrem Konto, und antwortet mit ihrer id. Ein Konto hält 3 Sitzungen gleichzeitig; eine endet nach 15 Minuten ohne Nutzung oder nach 8 Stunden.

2. 02

   Die Dateien hochladen

   PUT /sessions/{id}/files/{name}, mit der Datei als rohem Body: das Modell und seine Konfiguration. Ein Name ist der Dateiname in der Sitzung, nie ein Pfad auf dem Server.

3. 03

   Öffnen und konfigurieren

   Der Befehl model.open mit {"path": "house.skp"} öffnet das Modell und antwortet mit seinen Darstellungen in sections. config.set mit {"path": "standard.occc"} wendet die Konfiguration an; eine Konfiguration, die das Format verletzt, wird ganz abgelehnt, mit allen Fehlern.

4. 04

   Ansehen, falls nötig

   preview.render liefert eine Darstellung als PNG, als JPEG oder als SVG selbst, bis 2048 Pixel an der längeren Seite. Ein Export braucht sie nicht.

5. 05

   Exportieren

   export mit einem format — svg, dxf, pdf, png oder jpg —, den zu zeichnenden sections — der Name einer Darstellung oder eine Liste davon — und out: eine Datei für eine Zeichnung, ein Ordner für mehrere. merged macht daraus ein PDF.

6. 06

   Herunterladen, dann die Sitzung beenden

   GET /sessions/{id}/files/{name} lädt herunter, was der Export geschrieben hat; DELETE /sessions/{id} beendet die Sitzung, und ihre Dateien werden mit ihr gelöscht.

KEY=occ_sk_…                                  # Account › API keys
API=https://api.occlusia.app/v1/engine
AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"

# 1. A session: an engine of your own, with its own files
S=$(curl -s -X POST $API/sessions -H "$AUTH" | jq -r .id)

# 2. The model and your graphic standard
curl -T house.skp $API/sessions/$S/files/house.skp -H "$AUTH"
curl -T standard.occc $API/sessions/$S/files/standard.occc -H "$AUTH"

# 3. Open the model (1 credit), apply the configuration (free)
curl $API/sessions/$S/commands/model.open -H "$AUTH" -H "$JSON" -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/config.set -H "$AUTH" -H "$JSON" -d '{"path":"standard.occc"}'

# 4. Export one view as DXF (1 credit per drawing)
curl $API/sessions/$S/commands/export -H "$AUTH" -H "$JSON" \
     -d '{"format":"dxf","sections":"Section A-A","out":"section-a.dxf"}'

# 5. Download it, then end the session: its files are deleted with it
curl -o section-a.dxf $API/sessions/$S/files/section-a.dxf -H "$AUTH"
curl -X DELETE $API/sessions/$S -H "$AUTH"

Die Beispiele exportieren die erste Darstellung des Modells. sections.list listet alle auf und sagt, welche aktiv ist; objects.list, annotations.list und levels.list listen den Rest des Modells auf.

• "sections": "Section A-A" exportiert eine Darstellung; ["Section A-A", "Ground floor plan"] mehrere, jede als eigene Datei im Ordner out — oder ein PDF mit "merged": true.
• page legt die PDF-Seite jeder Darstellung fest — format, orientation, scale_mode fit oder custom mit seinem scale_denominator (1:N), margins_mm —, pages eine Darstellung nach der anderen; image legt Größe oder Maßstab, Auflösung, Hintergrund und Qualität eines PNG oder JPEG fest.
• export.config liest die Seiteneinrichtung jeder Darstellung, und export.setup ändert sie ohne Export, wie es der Exportdialog tut.
• Ein Export antwortet mit den Dateien, die er geschrieben hat, und dem, was er gekostet hat; GET /sessions/{id}/files listet die Dateien der Sitzung auf.

Jede Einstellung, die eine Konfiguration enthält, lässt sich auch Befehl für Befehl setzen: object.set für ein Objekt, object.apply_preset für eine Schraffurvorgabe, layers.create und layers.update für die DXF-Layer, section.set für eine Darstellung, annotation.set und level.set für Beschriftungen und Höhenkoten. engine.schema listet jede Einstellung und ihre Werte auf; config.get antwortet mit der gesamten Konfiguration, zum Aufbewahren als .occc-Datei.

Ein PDF-Satz kann Minuten dauern. Senden Sie seinen Befehl mit Prefer: respond-async: Er antwortet sofort mit 202 und einem Job, und GET /sessions/{id}/jobs/{job} sagt, ob der Job läuft, mit seinem Ergebnis fertig ist oder mit seinem Fehler fehlgeschlagen ist. GET /sessions/{id}/events streamt als Server-Sent Events, was die Engine tut: progress, message, export, job, ended.

• Jede Ablehnung ist {"error": {"code", "message"}}, mit einem stabilen Code und dem dazugehörigen HTTP-Status.
• 429 mit cloud_limit oder rate_limited und 503 mit busy tragen Retry-After: So lange warten, dann dieselbe Anfrage erneut senden.
• Senden Sie mit einem Befehl einen Idempotency-Key: Eine Wiederholung nach einer verlorenen Antwort wird aus dem ersten Lauf beantwortet — nie erneut ausgeführt, nie doppelt berechnet.
• Jede Antwort trägt X-Request-Id: Geben Sie sie bei jeder Frage zu einer Anfrage an.

GET /v1/engine

Version und Build der Engine, ohne Schlüssel.

GET /v1/engine/openapi.json

Die gesamte API in OpenAPI.

GET /v1/engine/commands

Jeder Befehl, mit seinen Parametern als JSON Schema.

Jede Route, jede Grenze und jeder Fehlercode ist in API und MCP aufgeführt, unter Die REST-API.