Kiri Engine — 3D 扫描重建 API 技能

调用 KIRI Engine API 生成 3D 模型（照片级扫描 / 无特征物体扫描）或高斯泼溅（3DGS）资产

首次配置（必须）

1. 获取 API Key

1. 注册 KIRI Engine 开发者账号：https://www.kiriengine.com/
2. 在 API Settings 页面创建 API Key（格式：kiri-\x3Crandom-string>）
3. 注册地址：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. 算法选择

B. 输入方式

C. 各算法专属参数

Photo Scan：

Featureless Scan：

3DGS Scan：

标准工作流

┌─────────────────────────────────────────────────┐
│ 1. 检查 API Key 是否配置                          │
│ 2. 查询余额（确保足够）                            │
│ 3. 询问用户：算法 / 输入方式 / 参数               │
│ 4. 确认文件路径（视频或图片集）                    │
│ 5. 验证文件合规（分辨率、时长、数量）              │
│ 6. 上传文件 → 获取 serialize                     │
│ 7. 轮询任务状态（每 30~60 秒）                    │
│ 8. 任务完成 → 下载 zip（60 分钟有效）             │
│ 9. 解压到用户指定目录                             │
│ 10. 报告完成 + 资产路径                           │
└─────────────────────────────────────────────────┘

任务时长估算

⚠️ 长时间任务规则：超过 5 分钟必须主动汇报进度。

资产获取注意事项

1. 下载链接有效期 60 分钟 — 任务完成后必须立即下载
2. 服务器保留 3 天 — 超时自动删除，无法恢复
3. 下载后必须本地备份 — 建议存入 projects/\x3C项目名>/资产/3d/

错误处理

脚本调用方式

# 检查余额
.\scripts\kiri-engine.ps1 balance

# 上传视频（Photo Scan）
.\scripts\kiri-engine.ps1 photo-video -video "C:\path	o\video.mp4" -modelQuality 1 -textureQuality 1 -fileFormat OBJ -isMask 1 -textureSmoothing 1

# 上传图片集（Photo Scan）
.\scripts\kiri-engine.ps1 photo-image -images "C:\path	o\images\*.jpg" -modelQuality 2 -fileFormat GLB -isMask 1 -textureSmoothing 1

# 上传视频（Featureless Scan）
.\scripts\kiri-engine.ps1 featureless-video -video "C:\path	o\video.mp4" -fileFormat OBJ

# 上传图片集（3DGS Scan）
.\scripts\kiri-engine.ps1 3dgs-image -images "C:\path	o\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