shellgen 开放 API

v1 微信群 Ai_doc_so · 备注 3d

内腔驱动的参数化外壳生成服务，单位 mm。POST 一份 spec + holes，拿回可直接切片的 STL / STEP。 服务端无状态 —— 每个请求自带参数，不依赖界面里正在编辑的东西。

Base URLhttps://lei.la/3d
在线地址https://lei.la/3d（HTTPS，无需登录）
坐标系X 长 / Y 宽 / Z 高，Z=0 是贴木板的底面
鉴权未开启
任务保留60 分钟
并发建模串行，多请求自动排队
限制—

隐私与安全

不记录不写访问日志；请求参数不落盘、不入库，建模完即丢。
不保存参数任务表里只有任务 id、文件名、体积和指标，不含你提交的 spec / holes。
不接收上传预设接口只读。没有任何把配置写到服务器的入口 —— 要保存请在界面点「导出配置」，文件直接落到你本机。
不留垃圾产物放 out/api/<job_id>/，1 小时后自动删，也可 DELETE 立即清。
不联外网服务不向外发起任何请求；前端也全部走本地资源，没有 CDN。
不直接暴露后端只监听本机回环，对外一律走 https://lei.la/3d；--host 0.0.0.0 时强制要求 API Key，没设直接拒绝启动。
加固nosniff / 禁嵌入 / 无 referrer；CORS 默认关（--cors 才开）；路径限定挡 ../；并发上限 8。

端点

方法路径说明
GET/api/v1/health健康检查（免鉴权）
GET/api/v1/capabilities参数能力：字段、范围、枚举、坐标约定（免鉴权）
GET/api/v1/openapi.jsonOpenAPI 3.1，可导入 Postman / 生成 SDK
GET/api/v1/example可直接 POST 的完整示例请求体
POST/api/v1/build校验 + 建模，只回包围盒 / 体积 / 干涉，不落盘
POST/api/v1/export建模 + 落盘，回可下载的文件列表
GET/api/v1/jobs任务列表
GET/api/v1/jobs/{id}任务详情（文件清单 + 指标，不含参数）
GET/api/v1/jobs/{id}/{file}下载模型文件
DELETE/api/v1/jobs/{id}立即删除任务及其文件
GET/api/v1/presets预设列表（只读）
GET/api/v1/presets/{name}下载预设 JSON（只读，无上传接口）

最快上手

下例里的 $BASE 就是当前服务地址 https://lei.la/3d， 先 set BASE=https://lei.la/3d（PowerShell: $env:BASE="https://lei.la/3d"）。

1. 拿一份能直接用的请求体
curl -s $BASE/api/v1/example -o payload.json
2. 建模，看指标（约 0.5 秒）
curl -s -X POST $BASE/api/v1/build \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <你的 key>' \
  -d @payload.json
3. 导出 STL（返回下载地址）
curl -s -X POST $BASE/api/v1/export \
  -H 'Content-Type: application/json' \
  -d '{"spec":{"cav_l":37.2,"cav_w":25.3,"cav_h":18.8},
       "holes":[],"name":"mycase","formats":["stl"]}'
4. 下载
curl -OJ $BASE/api/v1/jobs/<job_id>/mycase_base.stl

请求体

spec外壳参数，全部可选。只给 cav_l/cav_w/cav_h 也行，其余取默认值，未知字段忽略。
holes开孔数组，每项一个孔。
name文件名前缀，默认 shell。
formats["stl"] / ["step"] / 两者，默认 ["stl"]。
partsbase 底座 / lid 上盖 / assembly 整装，默认全给。
tolSTL 网格弦高误差 mm，默认 0.05（越小越精细、文件越大）。
展开：37 个可调参数
加载中…

返回与错误

成功
{
  "ok": true,
  "job_id": "j20261021165938_2f89e8",
  "files": [
    { "part":"base", "fmt":"stl", "name":"demo_base.stl",
      "size":116184, "sha256":"…",
      "url":"https://lei.la/3d/api/v1/jobs/<id>/demo_base.stl" }
  ],
  "metrics": { "bbox":[57.6,30.1,21.6], … },
  "warnings": ["…"],
  "expires_in": 3600
}
失败
{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "参数校验未通过",
    "details": ["卡扣过盈 0.30 会把底座壁（0.10）挖穿"]
  }
}
400BAD_JSON / BAD_REQUEST / TOO_MANY_HOLES
401UNAUTHORIZED 缺或错 API Key
404NOT_FOUND 端点 / 任务 / 文件不存在
413BODY_TOO_LARGE 请求体超限
422VALIDATION_FAILED 参数不合法（details 里是逐条原因）

开孔怎么填

face-Y +Y -X +X TOP BOTTOM
shaperect 矩形 / round 圆孔（用 w 当直径）/ slot 腰形槽 / hex 六边形 / tri 三角孔
u / u_ref横向位置。基准 center 之外还有 left、right。基准面是真正被切的外表面，所以 left + u:0 就是齐外沿。
v / v_ref纵向位置。bottom 就是距底面（侧面就是 Z）。
n / pitch阵列数量与间距，n:2, pitch:10 就是左右各一个。
depth0 表示切穿。

(u, v) 永远按模型正方向走，不随面的朝向翻转。孔上端如果伸进裙边区 （split_z − skirt_h 以上），上盖裙边会同步开口 —— 这是正常的， warnings 里会提一句。

Python 客户端

# 仓库里带了一个只用标准库的完整示例
python examples/api_client.py
python examples/api_client.py --base https://lei.la/3d --key <你的 key>

跨域

CORS 默认关闭 —— 同源的网页界面不需要它，而开放它等于让任意网站都能调本机服务。 确实要从别的域名下的页面调用时，启动加 --cors，此时才返回 Access-Control-Allow-Origin: * 并处理 OPTIONS 预检。

鉴权

线上 https://lei.la/3d 已开启 API Key。建模和导出请求要带 X-API-Key: <key>（或 Authorization: Bearer <key>）； health / capabilities / openapi.json 始终免鉴权，方便探活。 网页界面走的是同源内部接口，不需要 key。 

# 自建部署时也可以自己指定 key（对外监听强制要求）
python app/server.py --port 8771 --api-key my-secret
# 或者
set SHELLGEN_API_KEY=my-secret && python app/server.py --port 8771