Install
openclaw skills install kiri-engineKiri Engine
调用 KIRI Engine API，通过视频或图片集生成照片级、无特征或高斯泼溅3D模型，支持多种输出格式与参数配置。
Kiri Engine — 3D 扫描重建 API 技能
调用 KIRI Engine API 生成 3D 模型（照片级扫描 / 无特征物体扫描）或高斯泼溅（3DGS）资产
首次配置（必须）
1. 获取 API Key
- 注册 KIRI Engine 开发者账号：https://www.kiriengine.com/
- 在 API Settings 页面创建 API Key（格式：
kiri-<random-string>） - 注册地址：https://www.kiriengine.com/api-settings
2. 存储 API Key
# 将 API Key 写入配置文件（仅本机可见）
$configPath = "$env:USERPROFILE\.kiri-engine-config.json"
@{ apiKey = "kiri-你的密钥" } | ConvertTo-Json | Set-Content $configPath -Encoding UTF8
3. 检查余额（可选，建议首次使用）
powershell -ExecutionPolicy Bypass -File scripts/kiri-engine.ps1 balance
扫描类型与参数
生成前必须向用户确认以下所有选项，缺一不可：
A. 算法选择
| 算法 | calculateType | 适用场景 | 输出格式 |
|---|---|---|---|
| Photo Scan（照片级扫描） | 1 | 常规物体、有纹理表面 | OBJ / FBX / GLB / USDZ / STL |
| Featureless Scan（无特征扫描） | 2 | 光滑/无纹理/反光表面（如陶瓷、金属） | OBJ / FBX / GLB / USDZ / STL |
| 3DGS Scan（高斯泼溅） | 3 | 真实感场景复刻、NeRF 替代方案 | PLY + 3DGS 格式 |
B. 输入方式
| 输入方式 | 约束 |
|---|---|
| 视频上传 | 分辨率 ≤ 1920×1080，时长 ≤ 3 分钟 |
| 图片集上传 | 20~300 张（最少 20 张保证质量） |
C. 各算法专属参数
Photo Scan：
| 参数 | 值域 | 默认 | 说明 |
|---|---|---|---|
| modelQuality | 1/2/3 | 1 | 模型精度（1=标准, 2=中, 3=高） |
| textureQuality | 1/2/3 | 1 | 贴图质量（同上） |
| fileFormat | OBJ/FBX/GLB/USDZ/STL | OBJ | 输出格式 |
| isMask | 0/1 | 1 | 是否自动抠背景 |
| textureSmoothing | 0/1 | 1 | 贴图平滑 |
Featureless Scan：
| 参数 | 值域 | 默认 | 说明 |
|---|---|---|---|
| fileFormat | OBJ/FBX/GLB/USDZ/STL | OBJ | 输出格式 |
3DGS Scan：
| 参数 | 值域 | 默认 | 说明 |
|---|---|---|---|
| isMesh | 0/1 | 0 | 是否生成网格 |
| isMask | 0/1 | 0 | 是否自动抠背景 |
标准工作流
┌─────────────────────────────────────────────────┐
│ 1. 检查 API Key 是否配置 │
│ 2. 查询余额（确保足够） │
│ 3. 询问用户：算法 / 输入方式 / 参数 │
│ 4. 确认文件路径（视频或图片集） │
│ 5. 验证文件合规（分辨率、时长、数量） │
│ 6. 上传文件 → 获取 serialize │
│ 7. 轮询任务状态（每 30~60 秒） │
│ 8. 任务完成 → 下载 zip（60 分钟有效） │
│ 9. 解压到用户指定目录 │
│ 10. 报告完成 + 资产路径 │
└─────────────────────────────────────────────────┘
任务时长估算
| 算法 | 输入规模 | 预估时长 |
|---|---|---|
| Photo Scan | 视频 / <50 张图 | 10~30 分钟 |
| Photo Scan | >100 张图 / 高质量 | 30~90 分钟 |
| Featureless Scan | 视频 / 图片集 | 15~40 分钟 |
| 3DGS Scan | 视频 | 20~60 分钟 |
| 3DGS Scan | >100 张图 | 40~120 分钟 |
⚠️ 长时间任务规则：超过 5 分钟必须主动汇报进度。
资产获取注意事项
- 下载链接有效期 60 分钟 — 任务完成后必须立即下载
- 服务器保留 3 天 — 超时自动删除，无法恢复
- 下载后必须本地备份 — 建议存入
projects/<项目名>/资产/3d/
错误处理
| HTTP 码 | 含义 | 处理 |
|---|---|---|
| 200 | 成功 | — |
| 400 | 参数错误 | 检查文件合规性（分辨率/数量/格式） |
| 401 | 未授权 | API Key 无效或过期，重新配置 |
| 403 | 余额不足 | 提醒用户充值 |
| 500 | 服务器错误 | 重试，若持续则反馈用户 |
脚本调用方式
# 检查余额
.\scripts\kiri-engine.ps1 balance
# 上传视频（Photo Scan）
.\scripts\kiri-engine.ps1 photo-video -video "C:\path\to\video.mp4" -modelQuality 1 -textureQuality 1 -fileFormat OBJ -isMask 1 -textureSmoothing 1
# 上传图片集（Photo Scan）
.\scripts\kiri-engine.ps1 photo-image -images "C:\path\to\images\*.jpg" -modelQuality 2 -fileFormat GLB -isMask 1 -textureSmoothing 1
# 上传视频（Featureless Scan）
.\scripts\kiri-engine.ps1 featureless-video -video "C:\path\to\video.mp4" -fileFormat OBJ
# 上传图片集（3DGS Scan）
.\scripts\kiri-engine.ps1 3dgs-image -images "C:\path\to\images\*.jpg" -isMesh 0 -isMask 0
# 查询任务状态
.\scripts\kiri-engine.ps1 status -serialize "796a6f52457844b4918db3eadd64becc"
# 下载模型（zip）
.\scripts\kiri-engine.ps1 download -serialize "796a6f52457844b4918db3eadd64becc" -output "C:\output\dir"
用户交互模板
生成前向用户确认：
🎬 KIRI Engine 3D 扫描任务
请确认以下参数：
1️⃣ 算法类型：Photo Scan / Featureless Scan / 3DGS Scan？
2️⃣ 输入方式：视频上传 / 图片集上传？
3️⃣ 文件路径：视频文件路径 或 图片集所在文件夹？
4️⃣ 输出格式：OBJ / FBX / GLB / USDZ / STL？（3DGS 除外）
5️⃣ 模型精度：标准(1) / 中(2) / 高(3)？（仅 Photo Scan）
6️⃣ 贴图质量：标准(1) / 中(2) / 高(3)？（仅 Photo Scan）
7️⃣ 自动抠背景：是(1) / 否(0)？
8️⃣ 贴图平滑：是(1) / 否(0)？（仅 Photo Scan）
9️⃣ 输出网格：是(1) / 否(0)？（仅 3DGS）
🔟 保存位置：模型下载到哪个目录？
⏱️ 预计生成时间：XX~XX 分钟
API 参考
- Base URL:
https://api.kiriengine.app/api/ - 官方文档: https://gentlebandit.feishu.cn/wiki/PsHawWV0gi2jePkmRoycwMwXnIc
- API Key 管理: https://www.kiriengine.com/api-settings