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-<random-string>）
3. 注册地址： https://www.kiriengine.com/api-settings

2. 存储 API Key#

powershell

# 将 API Key 写入配置文件（仅本机可见）
$configPath = "$env:USERPROFILE\.kiri-engine-config.json"
@{ apiKey = "kiri-你的密钥" } | ConvertTo-Json | Set-Content $configPath -Encoding UTF8

3. 检查余额（可选，建议首次使用）#

powershell

powershell -ExecutionPolicy Bypass -File scripts/kiri-engine.ps1 balance

---

扫描类型与参数#

生成前 必须向用户确认以下所有选项，缺一不可：

A. 算法选择#

算法calculateType适用场景输出格式Photo Scan（照片级扫描）1常规物体、有纹理表面OBJ / FBX / GLB / USDZ / STLFeatureless Scan（无特征扫描）2光滑/无纹理/反光表面（如陶瓷、金属）OBJ / FBX / GLB / USDZ / STL3DGS Scan（高斯泼溅）3真实感场景复刻、NeRF 替代方案PLY + 3DGS 格式

B. 输入方式#

输入方式约束视频上传分辨率 ≤ 1920×1080，时长 ≤ 3 分钟图片集上传20~300 张（最少 20 张保证质量）

C. 各算法专属参数#

Photo Scan：

参数值域默认说明modelQuality1/2/31模型精度（1=标准, 2=中, 3=高）textureQuality1/2/31贴图质量（同上）fileFormatOBJ/FBX/GLB/USDZ/STLOBJ输出格式isMask0/11是否自动抠背景textureSmoothing0/11贴图平滑

Featureless Scan：

参数值域默认说明fileFormatOBJ/FBX/GLB/USDZ/STLOBJ输出格式

3DGS Scan：

参数值域默认说明isMesh0/10是否生成网格isMask0/10是否自动抠背景

---

标准工作流#

text

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

---

任务时长估算#

算法输入规模预估时长Photo Scan视频 / <50 张图1030 分钟Photo Scan>100 张图 / 高质量3090 分钟Featureless Scan视频 / 图片集1540 分钟3DGS Scan视频2060 分钟3DGS Scan>100 张图40~120 分钟

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

---

资产获取注意事项#

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

---

错误处理#

HTTP 码含义处理200成功—400参数错误检查文件合规性（分辨率/数量/格式）401未授权API Key 无效或过期，重新配置403余额不足提醒用户充值500服务器错误重试，若持续则反馈用户

---

脚本调用方式#

powershell

# 检查余额
.\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"

---

用户交互模板#

生成前向用户确认：

text

🎬 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