Occlusia pour les programmes : l’API et les outils d’IA

Tout ce que fait l’application web, un programme peut le faire : ouvrir un modèle, lister ses objets et ses vues, modifier leurs réglages, appliquer une configuration, prévisualiser une vue, exporter en SVG, DXF, PDF ou en images. C’est le moteur même de l’application web : les dessins sont ceux de l’application, à l’octet près, tout comme ses refus et ses prix.

• MCP : un outil d’IA — Claude, ChatGPT, l’assistant d’un éditeur — se connecte à https://api.occlusia.app/v1/mcp avec la seule adresse, et vous l’approuvez sur occlusia.app. Il travaille ensuite sur vos modèles, avec vos propres mots.
• L’API REST : https://api.occlusia.app/v1/engine — le moteur pour un script, un serveur, une tâche d’intégration continue ou votre propre application, avec une clé d’API ou OAuth.

Donnez à votre outil d’IA l’adresse du serveur MCP d’Occlusia. La première fois, il vous envoie sur occlusia.app : connectez-vous si besoin, vérifiez quelle application demande et ce qu’elle pourra faire, et autorisez-la. Aucune clé à copier.

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

• Claude (claude.ai, les applications de bureau et mobiles) : Settings, Connectors, Add custom connector, puis l’adresse ci-dessus.
• ChatGPT : ajoutez un serveur MCP personnalisé avec l’adresse ci-dessus et OAuth comme authentification.
• Claude Code : claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp, puis /mcp pour vous connecter.
• Cursor, VS Code et autres outils : ajoutez un serveur MCP distant (Streamable HTTP) avec l’adresse ; ils vous connectent de la même façon.

Chaque application que vous autorisez apparaît dans votre compte, sous Applications connectées, avec ce qu’elle peut faire et le moment de sa dernière utilisation. Déconnectez-la depuis cette page et elle s’arrête aussitôt. Occlusia vous envoie un e-mail la première fois qu’une application se connecte.

Chaque commande est un outil qu’une IA peut appeler : ouvrir un modèle, lister ses objets, définir une hachure, générer un aperçu — renvoyé comme une image que le modèle voit —, exporter. Chaque outil a un titre, indique s’il ne fait que lire, modifie quelque chose ou remplace un fichier, et indique ce qu’il coûte.

• Un espace de travail : ce que l’IA ouvre, règle et exporte reste dans votre espace de travail d’une requête à l’autre, et d’une conversation à l’autre, tant qu’il sert. Il prend fin après un moment d’inactivité, ou quand l’IA le réinitialise.
• Vos fichiers : l’IA vous donne une page où déposer votre modèle — un modèle .skp, .ifc, .fbx ou .occs, un projet .occp —, ou le récupère depuis un lien public ; elle vous rend ce qu’elle a exporté sous forme de liens de téléchargement.
• Votre compte : vos crédits, leur historique, les prix et vos achats. Quand il vous reste peu de crédits, l’IA peut préparer un achat : elle vous donne un lien vers occlusia.app, où vous le vérifiez et le payez — l’IA n’achète jamais rien.
• Un guide et une référence que l’IA lit d’elle-même (le flux de travail, chaque réglage et ses valeurs), et des prompts prêts à l’emploi : faire des dessins à partir d’un modèle, exporter un jeu de dessins, passer en revue le compte.

Le serveur parle toutes les révisions actuelles de MCP (2026-07-28, et de 2025-11-25 en remontant jusqu’à 2025-03-26). Une clé d’API fonctionne aussi, dans les outils qui l’envoient comme en-tête :

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

Un script, un serveur ou une tâche d’intégration continue se connecte avec une clé d’API. Créez-en une dans votre compte, sous Clés d’API : un nom, une durée de validité et une connexion datant de quelques minutes. La clé n’est affichée qu’une fois ; Occlusia n’en garde qu’une empreinte.

• Une clé lit votre compte et dépense vos crédits ; elle ne gère jamais le compte.
• La page Clés d’API liste chaque clé par son nom et ses quatre derniers caractères, avec le moment et l’adresse de sa dernière utilisation. Un compte détient 20 clés au maximum.
• Révoquer une clé arrête aussitôt tout programme qui l’utilise. Occlusia vous envoie un e-mail à chaque création de clé.

https://api.occlusia.app/v1/engine exécute le moteur sur les serveurs d’Occlusia, chaque requête avec une clé — Authorization: Bearer occ_sk_… — ou le jeton d’accès d’une application. Une session est un moteur à vous avec ses propres fichiers : envoyez un modèle, exécutez des commandes, téléchargez ce qu’elles ont écrit, terminez la session.

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"

Les routes, sous /v1/engine ; … vaut /sessions/{id} :

POST /sessions

Ouvre une session. Un compte en détient 3 à la fois ; une session se termine après 15 minutes d’inactivité ou 8 heures.

PUT …/files/{name}

Envoie un fichier, le corps brut : 512 Mo au maximum, 2 Go par session.

POST …/commands/{command}

Exécute une commande, ses paramètres dans le corps JSON ; la réponse est celle de la commande. Avec Prefer: respond-async, une tâche est répondue aussitôt.

GET …/jobs/{job}

Une tâche : en cours, terminée avec son résultat, ou échouée avec son erreur.

GET …/events

Ce que fait le moteur, en événements envoyés par le serveur : progression, messages, exports.

GET …/files/{name}

Télécharge un fichier de la session. GET …/files les liste, DELETE en supprime un.

POST …/links

Un lien qui envoie ou télécharge un fichier pendant 15 minutes, sans la clé ; un lien d’envoi ouvert dans un navigateur est une page où déposer le fichier.

DELETE /sessions/{id}

Termine la session ; ses fichiers sont supprimés avec elle.

GET /commands

Chaque commande avec son JSON Schema ; toute l’API en OpenAPI à /openapi.json.

Un paramètre de fichier désigne un fichier de la session — "path": "house.skp", "out": "set.pdf" —, jamais un chemin sur le serveur. Les objets se désignent comme dans le navigateur de modèle — par leur nom, ou par leur chemin (Walls/South wall) —, les vues par leur nom. Une commande s’exécute à la fois dans une session ; les calculs — un modèle ouvert, un dessin, un export — s’exécutent deux à la fois par compte et attendent leur tour jusqu’à une minute, tandis qu’une liste ou un réglage n’attend jamais. 600 requêtes par minute et par clé.

• Idempotence : envoyez Idempotency-Key avec une commande, et une nouvelle tentative après une réponse perdue reçoit la réponse de la première exécution — jamais exécutée, jamais facturée deux fois.
• Identifiants de requête et limites : chaque réponse porte X-Request-Id (le vôtre, quand vous en envoyez un) et RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset.
• Le compte : GET /v1/auth/me, /v1/account/credits, /v1/account/credits/history et /v1/account/credits/purchases le lisent avec la même clé.
• Configuration de l’export : export.config et export.setup lisent et modifient la page PDF de chaque vue et la place du dessin sur la feuille, comme le fait la boîte de dialogue d’export.

Chaque refus est {"error": {"code", "message"}} avec un code stable : invalid_api_key (401), insufficient_credits (402), session_not_found (404), invalid_params (422), rate_limited, session_limit et cloud_limit (429 : l’allocation de l’accès anticipé est épuisée jusqu’à son Retry-After), busy (503 : réessayez après son Retry-After), credits_unavailable (503 : rien n’a été lancé, réessayez), et les codes propres à la commande quand elle refuse.

Une application à vous peut agir pour les comptes Occlusia de ses utilisateurs avec OAuth 2.1 : le flux par code d’autorisation avec PKCE (S256), clients publics. Les métadonnées du serveur d’autorisation se trouvent à https://api.occlusia.app/.well-known/oauth-authorization-server ; enregistrez-y votre client, ou désignez-le par l’adresse https d’un document de métadonnées client.

• Portées : engine — ouvrir, configurer, dessiner et exporter, en dépensant les crédits de l’utilisateur —, et account — lire le compte, ses crédits et ses achats.
• Demandez la ressource que vous appelez (resource=https://api.occlusia.app/v1/engine ou …/v1/mcp) : un jeton ne fonctionne que là.
• Un jeton d’accès dure une heure ; les jetons d’actualisation sont renouvelés à chaque utilisation. L’utilisateur voit votre application sous Applications connectées et peut l’y déconnecter.

• Occlusia conserve une clé d’API sous forme d’empreinte, jamais telle quelle : une clé perdue ne peut pas être réaffichée, seulement révoquée.
• Une application connectée détient des jetons qu’Occlusia ne conserve que sous forme d’empreintes ; ils n’ouvrent que ce que vous avez autorisé, et plus rien dès que vous déconnectez l’application.
• Chaque session de l’API s’exécute dans un moteur à elle, sous un utilisateur système à elle, sans autre réseau que les services d’Occlusia. Ses fichiers sont supprimés quand elle se termine.
• Un fichier récupéré depuis un lien provient uniquement de l’internet public, jamais d’un réseau privé.
• Créer une clé ou connecter une application demande une connexion datant de quelques minutes, et Occlusia vous envoie un e-mail à chaque fois.