跳到文档内容
搜索文档
浏览文档
语言中文
EnglishFrançais中文NederlandsDeutschالعربيةहिन्दी

API 和 MCP

面向程序的 Occlusia：API 与 AI 工具

用一个地址连接 Claude、ChatGPT 或任何 AI 工具，或通过 REST API 从您自己的代码驱动 Occlusia。与网页应用相同的引擎，在这里运行于 Occlusia 的服务器上：同样的图纸，用积分支付。

两种接入方式

网页应用能做的一切，程序都能做：打开模型，列出其对象和视图，修改它们的设置，应用配置，预览视图，导出 SVG、DXF、PDF 或图像。这正是网页应用自己的引擎：图纸与应用中的逐字节相同，拒绝与价格也一样。

  • MCP：AI 工具——Claude、ChatGPT、编辑器中的助手——仅凭地址即可连接到 https://api.occlusia.app/v1/mcp，由您在 occlusia.app 上批准。之后它就能按您自己的话处理您的模型。
  • REST API：https://api.occlusia.app/v1/engine——供脚本、服务器、CI 任务或您自己的应用使用的引擎，通过 API 密钥或 OAuth 访问。
指南REST API 指南通过 HTTP 从模型到 DXF，附 cURL、JavaScript、TypeScript 和 Python 示例。阅读指南指南MCP 指南连接 AI 工具，批准它，并在一次对话中完成从上传到导出的全过程。阅读指南

连接 AI 工具

把 Occlusia 的 MCP 服务器地址交给您的 AI 工具。第一次连接时，它会将您带到 occlusia.app：如有需要请先登录，确认是哪个应用在请求、它将能做什么，然后允许它。无需复制任何密钥。

https://api.occlusia.app/v1/mcp
  • Claude（claude.ai、桌面和移动应用）：Settings、Connectors、Add custom connector，然后填入上面的地址。
  • ChatGPT：添加一个自定义 MCP 服务器，填入上面的地址，并以 OAuth 作为身份验证方式。
  • Claude Code：claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp，然后运行 /mcp 登录。
  • Cursor、VS Code 及其他工具：用该地址添加一个远程 MCP 服务器（Streamable HTTP）；它们会以同样的方式让您登录。

您允许的每个应用都会出现在您账户中的 已连接的应用 下，并显示它能做什么以及最近一次使用的时间。在那里断开它，它会立即停止。应用首次连接时，Occlusia 会给您发送邮件。

AI 工具（MCP）

每条命令都是 AI 可以调用的工具：打开模型、列出其对象、设置填充图案、渲染预览——以模型能看到的图像作答——、导出。每个工具都有标题，会说明它是只读取、会修改内容还是会替换文件，并说明其费用。

  • 工作区：AI 打开、设置和导出的内容会保留在您的工作区中，从一个请求到下一个请求，从一次对话到下一次对话，只要工作区仍在使用。闲置一段时间后，或 AI 将其重置时，工作区即结束。
  • 您的文件：AI 会给您一个页面，用于拖放模型——.skp、.ifc、.fbx 或 .occs 模型、.occp 项目——，或从公开链接获取模型；导出的内容会以下载链接的形式交还给您。
  • 您的账户：您的积分、积分记录、价格和购买记录。积分所剩不多时，AI 可以准备一笔购买：它会给您一个 occlusia.app 的链接，您在那里核对并付款——AI 从不购买任何东西。
  • 指南与参考资料，供 AI 自行阅读（工作流程、每项设置及其取值），以及现成的提示词：从模型生成图纸、导出一套图纸、检查账户。

服务器支持 MCP 的所有现行修订版（2026-07-28，以及从 2025-11-25 往前直到 2025-03-26）。API 密钥同样可用，适用于以请求头发送密钥的工具：

claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp \
  --header "Authorization: Bearer occ_sk_…"
使用 Claude Code，或在其他 AI 工具的 MCP 设置中。

API 密钥

脚本、服务器或 CI 任务使用 API 密钥登录。在您的账户中 API 密钥 下创建一个：名称、有效期，以及最近几分钟内的登录。密钥只显示一次；Occlusia 只保留它的指纹。

  • 密钥读取您的账户并消耗您的积分；它从不管理账户。
  • API 密钥 页面按名称和最后四个字符列出每个密钥，并显示其最近一次使用的时间和地址。一个账户最多拥有 20 个密钥。
  • 撤销密钥会立即停止所有使用它的程序。每次创建密钥时，Occlusia 都会给您发送邮件。

REST API

https://api.occlusia.app/v1/engine 在 Occlusia 的服务器上运行引擎，每个请求都带上密钥——Authorization: Bearer occ_sk_…——或某个应用的访问令牌。会话是您专属的引擎，拥有自己的文件：上传模型、运行命令、下载命令写出的文件、结束会话。

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"
模型进，PDF 出，会话结束。

各路由位于 /v1/engine 下；… 表示 /sessions/{id}：

POST /sessions
打开一个会话。一个账户同时最多 3 个；会话在 15 分钟未使用或 8 小时后结束。
PUT …/files/{name}
上传文件，原始请求体：最多 512 MB，每个会话 2 GB。
POST …/commands/{command}
运行一条命令，其参数为 JSON 请求体；回答即命令的回答。带 Prefer: respond-async 时会立即返回一个任务。
GET …/jobs/{job}
任务：运行中、已完成并附结果，或已失败并附错误。
GET …/events
引擎的动态，以服务器发送事件呈现：进度、消息、导出。
GET …/files/{name}
下载会话中的文件。GET …/files 列出所有文件，DELETE 删除一个。
POST …/links
无需密钥、在 15 分钟内上传或下载一个文件的链接；上传链接在浏览器中打开时，是一个可拖放文件的页面。
DELETE /sessions/{id}
结束会话；其文件随之删除。
GET /commands
每条命令及其 JSON Schema；完整 API 的 OpenAPI 位于 /openapi.json。

文件参数指的是会话中的文件——"path": "house.skp"、"out": "set.pdf"——，绝不是服务器上的路径。对象的命名方式与模型浏览器相同——按名称或路径（Walls/South wall）——，视图按名称。每个会话一次运行一条命令；需要计算的操作——打开模型、生成图纸、导出——每个账户同时运行两个，最多等待一分钟轮到自己，而列表或设置从不等待。每个密钥每分钟 600 个请求。

  • 幂等性：随命令发送 Idempotency-Key，在回答丢失后重试时，将得到第一次运行的回答——绝不会运行两次，也绝不会收费两次。
  • 请求 ID 与限额：每个回答都带有 X-Request-Id（如果您发送了自己的 ID，则为您的 ID）以及 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset。
  • 账户：GET /v1/auth/me、/v1/account/credits、/v1/account/credits/history 和 /v1/account/credits/purchases 使用同一密钥读取账户。
  • 导出设置：export.config 和 export.setup 读取并修改每个视图的 PDF 页面以及图纸在纸张上的位置，与导出对话框的作用相同。

每次拒绝都是 {"error": {"code", "message"}}，附带稳定的代码：invalid_api_key（401）、insufficient_credits（402）、session_not_found（404）、invalid_params（422）、rate_limited、session_limit 和 cloud_limit（429：抢先体验额度已用完，直到其 Retry-After）、busy（503：在其 Retry-After 之后重试）、credits_unavailable（503：未执行任何操作，请重试），以及命令拒绝时自身的代码。

您自己的应用（OAuth）

您的应用可以通过 OAuth 2.1 代表其用户的 Occlusia 账户操作：带 PKCE（S256）的授权码流程，公共客户端。授权服务器的元数据位于 https://api.occlusia.app/.well-known/oauth-authorization-server；请在那里注册您的客户端，或用客户端元数据文档的 https 地址来标识它。

  • 权限范围：engine——打开、配置、绘制和导出，消耗用户的积分——，以及 account——读取账户、其积分和购买记录。
  • 请求您要调用的资源（resource=https://api.occlusia.app/v1/engine 或 …/v1/mcp）：令牌只在那里有效。
  • 访问令牌有效期为一小时；刷新令牌每次使用后都会轮换。用户可在 已连接的应用 下看到您的应用，并可在那里断开它。

安全与隐私

  • Occlusia 以指纹形式存储 API 密钥，从不存储密钥本身：丢失的密钥无法再次显示，只能撤销。
  • 已连接的应用持有的令牌，Occlusia 仅以指纹形式保存；它们只能打开您允许的内容，一旦您断开该应用，便什么也打不开。
  • 每个 API 会话都在专属的引擎中、以专属的系统用户运行，除 Occlusia 的服务外不能访问任何网络。会话结束时其文件即被删除。
  • 从链接获取的文件只来自公共互联网，绝不来自私有网络。
  • 创建密钥或连接应用需要最近几分钟内的登录，Occlusia 每次都会通过邮件通知您。