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

API 和 MCP

通过 HTTP，从模型到图纸

完整的 REST API 工作流程——会话、文件、配置、预览、导出、下载——以及用 cURL、JavaScript、TypeScript 和 Python 编写的同一程序。

开始之前

  • 一个 Occlusia 账户和一个 API 密钥，在您账户中的 API 密钥 下创建。请将密钥保存在环境变量中：示例读取 OCCLUSIA_API_KEY。
  • 一个模型：由 SketchUp 2021 或更高版本保存的 .skp 文件，或 .ifc、.fbx 或 .occs 文件，最大 512 MB。
  • 您的图形标准，作为配置，通过 Occlusia Studio 的 Export › Configuration (.occc) 导出——也可以没有，此时模型按默认设置绘制。
  • 点数，或抢先体验账户：打开模型和每次导出都消耗点数（API 和 MCP，费用说明）。

六个步骤

  1. 01

    打开会话

    POST /sessions 启动一个属于您自己、登录到您账户的引擎，并返回其 id。每个账户同时可有 3 个会话；会话在闲置 15 分钟后或满 8 小时后结束。

  2. 02

    上传文件

    PUT /sessions/{id}/files/{name}，以文件作为原始请求体：模型及其配置。名称是文件在会话中的名称，绝不是服务器上的路径。

  3. 03

    打开并配置

    命令 model.open 配合 {"path": "house.skp"} 打开模型，并在 sections 中返回其视图。config.set 配合 {"path": "standard.occc"} 应用配置；破坏格式的配置会被整体拒绝，并列出所有错误。

  4. 04

    需要时预览

    preview.render 以 PNG、JPEG 或 SVG 本身返回一个视图，长边最多 2048 像素。导出并不需要它。

  5. 05

    导出

    export 带上 format——svg、dxf、pdf、png 或 jpg——、要绘制的 sections——一个视图的名称，或其列表——以及 out：单张图纸用文件，多张用文件夹。merged 会将它们合成一份 PDF。

  6. 06

    下载，然后结束会话

    GET /sessions/{id}/files/{name} 下载导出所写入的内容；DELETE /sessions/{id} 结束会话，其文件随之删除。

同一程序的四种语言版本

输入一个模型，输出其第一个视图的 DXF，即使某一步失败，会话也会被结束。每种语言在遇到拒绝时都会停止，并给出其状态码和错误的响应体。

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"

这些示例导出模型的第一个视图。sections.list 列出所有视图并说明哪一个处于活动状态；objects.list、annotations.list 和 levels.list 列出模型的其余内容。

选择视图和格式

  • "sections": "Section A-A" 导出一个视图；["Section A-A", "Ground floor plan"] 导出多个视图，每个视图在 out 文件夹中各成一个文件——或用 "merged": true 合成一份 PDF。
  • page 设置每个视图的 PDF 页面——format、orientation、scale_mode（fit 或 custom，后者带其 scale_denominator (1:N)）、margins_mm——，pages 则一次设置一个视图；image 设置 PNG 或 JPEG 的尺寸或比例、分辨率、背景和质量。
  • export.config 读取每个视图的页面设置，export.setup 则在不导出的情况下修改它，就像导出对话框那样。
  • 导出会返回它所写入的文件及其费用；GET /sessions/{id}/files 列出会话的文件。

不使用配置文件进行样式设置

配置所含的每项设置，也可以逐条命令设置：object.set 用于对象，object.apply_preset 用于填充图案预设，layers.create 和 layers.update 用于 DXF 图层，section.set 用于视图，annotation.set 和 level.set 用于注释和标高。engine.schema 列出每项设置及其取值；config.get 返回整份配置，可保存为 .occc 文件。

耗时较长的导出：作业和事件

一套 PDF 可能需要几分钟。发送其命令时带上 Prefer: respond-async：它会立即返回 202 和一个作业，GET /sessions/{id}/jobs/{job} 会说明作业是在运行、已完成并附结果，还是失败并附错误。GET /sessions/{id}/events 以 server-sent events 推送引擎的动作：progress、message、export、job、ended。

错误和重试

  • 每次拒绝都是 {"error": {"code", "message"}}，带有稳定的代码和对应的 HTTP 状态码。
  • 带有 cloud_limit 或 rate_limited 的 429，以及带有 busy 的 503，都带有 Retry-After：等待相应的时间，然后重新发送同一个请求。
  • 随命令发送 Idempotency-Key：响应丢失后的重试会直接返回第一次运行的结果——绝不会重复运行，也绝不会重复收费。
  • 每个响应都带有 X-Request-Id：就任何请求提问时请附上它。

参考

GET /v1/engine
引擎的版本和构建号，无需密钥。
GET /v1/engine/openapi.json
完整的 API，以 OpenAPI 描述。
GET /v1/engine/commands
每条命令，其参数以 JSON Schema 描述。

每条路由、限制和错误代码都列在 API 和 MCP 中，位于 REST API 一节。