Kiri Engine

调用 KIRI Engine API，通过视频或图片集生成照片级、无特征或高斯泼溅3D模型，支持多种输出格式与参数配置。

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 / 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	是否自动抠背景

---

标准工作流

text

┌─────────────────────────────────────────────────┐
│ 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 分钟必须主动汇报进度。

---

资产获取注意事项

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