Occlusia für Programme: die API und KI-Werkzeuge

Alles, was die Web-App kann, kann auch ein Programm: ein Modell öffnen, seine Objekte und Ansichten auflisten, ihre Einstellungen ändern, eine Konfiguration anwenden, eine Ansicht in der Vorschau zeigen, als SVG, DXF, PDF oder Bild exportieren. Es ist die eigene Engine der Web-App: Die Zeichnungen sind die der App, Byte für Byte, ebenso ihre Ablehnungen und ihre Preise.

• MCP: Ein KI-Werkzeug — Claude, ChatGPT, der Assistent eines Editors — verbindet sich allein über die Adresse mit https://api.occlusia.app/v1/mcp, und Sie bestätigen es auf occlusia.app. Danach arbeitet es mit Ihren Modellen, in Ihren eigenen Worten.
• Die REST-API: https://api.occlusia.app/v1/engine — die Engine für ein Skript, einen Server, einen CI-Job oder eine eigene App, mit einem API-Schlüssel oder OAuth.

Geben Sie Ihrem KI-Werkzeug die Adresse des MCP-Servers von Occlusia. Beim ersten Mal schickt es Sie zu occlusia.app: Melden Sie sich bei Bedarf an, prüfen Sie, welche App fragt und was sie tun darf, und lassen Sie sie zu. Es muss kein Schlüssel kopiert werden.

https://api.occlusia.app/v1/mcp

• Claude (claude.ai, die Desktop- und Mobil-Apps): Settings, Connectors, Add custom connector, dann die Adresse oben.
• ChatGPT: Fügen Sie einen benutzerdefinierten MCP-Server mit der Adresse oben und OAuth als Authentifizierung hinzu.
• Claude Code: claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp, dann /mcp, um sich anzumelden.
• Cursor, VS Code und andere Werkzeuge: Fügen Sie einen Remote-MCP-Server (Streamable HTTP) mit der Adresse hinzu; sie melden Sie auf dieselbe Weise an.

Jede App, die Sie zulassen, erscheint in Ihrem Konto unter Verbundene Apps, mit dem, was sie tun darf, und wann sie zuletzt verwendet wurde. Trennen Sie sie dort, und sie stoppt sofort. Occlusia schickt Ihnen eine E-Mail, wenn sich eine App zum ersten Mal verbindet.

Jeder Befehl ist ein Werkzeug, das eine KI aufrufen kann: ein Modell öffnen, seine Objekte auflisten, eine Schraffur setzen, eine Vorschau erzeugen — als Bild beantwortet, das das Modell sieht —, exportieren. Jedes Werkzeug hat einen Titel, sagt, ob es nur liest, etwas ändert oder eine Datei ersetzt, und sagt, was es kostet.

• Ein Arbeitsbereich: Was die KI öffnet, einstellt und exportiert, bleibt von einer Anfrage zur nächsten und von einem Gespräch zum nächsten in Ihrem Arbeitsbereich, solange er genutzt wird. Er endet nach einer Weile ohne Nutzung oder wenn die KI ihn zurücksetzt.
• Ihre Dateien: Die KI gibt Ihnen eine Seite, auf die Sie Ihr Modell ziehen — ein .skp-, .ifc-, .fbx- oder .occs-Modell, ein .occp-Projekt —, oder holt es von einem öffentlichen Link; was sie exportiert hat, gibt sie als Download-Links zurück.
• Ihr Konto: Ihre Credits, deren Verlauf, die Preise und Ihre Käufe. Werden die Credits knapp, kann die KI einen Kauf vorbereiten: Sie gibt Ihnen einen Link zu occlusia.app, wo Sie ihn prüfen und bezahlen — die KI kauft nie etwas.
• Ein Leitfaden und eine Referenz, die die KI selbstständig liest (der Arbeitsablauf, jede Einstellung und ihre Werte), und fertige Prompts: Zeichnungen aus einem Modell erstellen, einen Satz Zeichnungen exportieren, das Konto prüfen.

Der Server spricht jede aktuelle Revision von MCP (2026-07-28 sowie 2025-11-25 zurück bis 2025-03-26). Ein API-Schlüssel funktioniert auch, in Werkzeugen, die ihn als Header senden:

claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp \
  --header "Authorization: Bearer occ_sk_…"

Ein Skript, ein Server oder ein CI-Job meldet sich mit einem API-Schlüssel an. Erstellen Sie einen in Ihrem Konto unter API-Schlüssel: ein Name, eine Gültigkeitsdauer und eine Anmeldung aus den letzten Minuten. Der Schlüssel wird einmal angezeigt; Occlusia bewahrt nur einen Fingerabdruck davon auf.

• Ein Schlüssel liest Ihr Konto und verbraucht Ihre Credits; er verwaltet das Konto nie.
• Die Seite API-Schlüssel listet jeden Schlüssel mit Namen und seinen letzten vier Zeichen auf, dazu wann und von welcher Adresse er zuletzt verwendet wurde. Ein Konto hat höchstens 20 Schlüssel.
• Das Widerrufen eines Schlüssels stoppt sofort jedes Programm, das ihn verwendet. Occlusia schickt Ihnen bei jedem neuen Schlüssel eine E-Mail.

https://api.occlusia.app/v1/engine führt die Engine auf den Servern von Occlusia aus, jede Anfrage mit einem Schlüssel — Authorization: Bearer occ_sk_… — oder dem Zugriffstoken einer App. Eine Sitzung ist eine eigene Engine mit eigenen Dateien: ein Modell hochladen, Befehle ausführen, herunterladen, was sie geschrieben haben, die Sitzung beenden.

KEY=occ_sk_…
API=https://api.occlusia.app/v1/engine
S=$(curl -s -X POST $API/sessions -H "Authorization: Bearer $KEY" | jq -r .id)
curl -T house.skp $API/sessions/$S/files/house.skp -H "Authorization: Bearer $KEY"
curl $API/sessions/$S/commands/model.open -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/export -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"format":"pdf","sections":"Section AA","out":"section.pdf"}'
curl -o section.pdf $API/sessions/$S/files/section.pdf -H "Authorization: Bearer $KEY"
curl -X DELETE $API/sessions/$S -H "Authorization: Bearer $KEY"

Die Routen, unter /v1/engine; … steht für /sessions/{id}:

POST /sessions

Öffnet eine Sitzung. Ein Konto hat 3 gleichzeitig; eine Sitzung endet nach 15 Minuten ohne Nutzung oder nach 8 Stunden.

PUT …/files/{name}

Lädt eine Datei hoch, der rohe Body: höchstens 512 MB, 2 GB pro Sitzung.

POST …/commands/{command}

Führt einen Befehl aus, seine Parameter im JSON-Body; die Antwort ist die des Befehls. Mit Prefer: respond-async wird sofort ein Job geantwortet.

GET …/jobs/{job}

Ein Job: läuft, erledigt mit seinem Ergebnis oder fehlgeschlagen mit seinem Fehler.

GET …/events

Was die Engine tut, als Server-Sent Events: Fortschritt, Meldungen, Exporte.

GET …/files/{name}

Lädt eine Datei der Sitzung herunter. GET …/files listet sie auf, DELETE löscht eine.

POST …/links

Ein Link, der eine Datei 15 Minuten lang hoch- oder herunterlädt, ohne den Schlüssel; ein Upload-Link, im Browser geöffnet, ist eine Seite, auf die Sie die Datei ziehen.

DELETE /sessions/{id}

Beendet die Sitzung; ihre Dateien werden mit ihr gelöscht.

GET /commands

Jeder Befehl mit seinem JSON Schema; die ganze API als OpenAPI unter /openapi.json.

Ein Dateiparameter benennt eine Datei der Sitzung — "path": "house.skp", "out": "set.pdf" —, nie einen Pfad auf dem Server. Objekte werden wie im Modell-Browser benannt — mit Namen oder Pfad (Walls/South wall) —, Ansichten mit ihrem Namen. Pro Sitzung läuft ein Befehl auf einmal; Berechnungen — ein geöffnetes Modell, eine Zeichnung, ein Export — laufen pro Konto zwei auf einmal und warten bis zu einer Minute auf ihren Platz, während eine Liste oder eine Einstellung nie wartet. 600 Anfragen pro Minute und Schlüssel.

• Idempotenz: Senden Sie Idempotency-Key mit einem Befehl, und eine Wiederholung nach einer verlorenen Antwort wird aus dem ersten Lauf beantwortet — nie zweimal ausgeführt, nie zweimal berechnet.
• Anfrage-IDs und Limits: Jede Antwort trägt X-Request-Id (Ihre, wenn Sie eine senden) sowie RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.
• Das Konto: GET /v1/auth/me, /v1/account/credits, /v1/account/credits/history und /v1/account/credits/purchases lesen es mit demselben Schlüssel.
• Export-Einrichtung: export.config und export.setup lesen und ändern die PDF-Seite jeder Ansicht und die Lage der Zeichnung auf dem Blatt, wie es der Exportdialog tut.

Jede Ablehnung ist {"error": {"code", "message"}} mit einem festen Code: invalid_api_key (401), insufficient_credits (402), session_not_found (404), invalid_params (422), rate_limited, session_limit und cloud_limit (429: das Kontingent des frühen Zugangs ist bis zu seinem Retry-After aufgebraucht), busy (503: nach dem Retry-After erneut versuchen), credits_unavailable (503: nichts wurde ausgeführt, erneut versuchen) und die eigenen Codes des Befehls, wenn er ablehnt.

Eine App von Ihnen kann mit OAuth 2.1 für die Occlusia-Konten ihrer Benutzer handeln: der Autorisierungscode-Flow mit PKCE (S256), öffentliche Clients. Die Metadaten des Autorisierungsservers liegen unter https://api.occlusia.app/.well-known/oauth-authorization-server; registrieren Sie Ihren Client dort, oder benennen Sie ihn mit der https-Adresse eines Client-Metadatendokuments.

• Scopes: engine — öffnen, konfigurieren, zeichnen und exportieren, mit den Credits des Benutzers —, und account — das Konto, seine Credits und Käufe lesen.
• Fordern Sie die Ressource an, die Sie aufrufen (resource=https://api.occlusia.app/v1/engine oder …/v1/mcp): Ein Token funktioniert nur dort.
• Ein Zugriffstoken gilt eine Stunde; Refresh-Tokens rotieren bei jeder Verwendung. Der Benutzer sieht Ihre App unter Verbundene Apps und kann sie dort trennen.

• Occlusia speichert einen API-Schlüssel als Fingerabdruck, nie im Klartext: Ein verlorener Schlüssel kann nicht erneut angezeigt, nur widerrufen werden.
• Eine verbundene App hält Tokens, die Occlusia nur als Fingerabdrücke speichert; sie öffnen nur, was Sie erlaubt haben, und nichts mehr, sobald Sie die App trennen.
• Jede API-Sitzung läuft in einer eigenen Engine, unter einem eigenen Systembenutzer, ohne anderes Netzwerk als die Dienste von Occlusia. Ihre Dateien werden gelöscht, wenn sie endet.
• Eine über einen Link geholte Datei kommt nur aus dem öffentlichen Internet, nie aus einem privaten Netzwerk.
• Einen Schlüssel erstellen oder eine App verbinden verlangt eine Anmeldung aus den letzten Minuten, und Occlusia informiert Sie jedes Mal per E-Mail.