---
name: tripo-3d
description: 用 Tripo AI 生成与加工 3D 模型资产：文生3D、图生3D、多视图、批量生成，以及重拓扑、绑定、动画、分割、纹理、PBR、UV、格式导出与下载。适用于需要 3D 模型、角色、道具、建筑或格式转换的场景。
---

# Tripo 3D 生成与加工技能

当用户需要生成 3D 模型、角色、道具、建筑，或对已有模型做重拓扑/绑定/动画/贴图/导出时使用本技能。

## 调用方式

本技能对应命令行工具 `tripocli`。按环境选择其一：

```bash
tripocli --version                       # 1) 已安装到 PATH（推荐）
<项目目录>/tripocli --version             # 2) 直接用仓库里的入口（零依赖，无需安装）
```

若尚未安装，进到项目目录后安装（纯标准库，无第三方依赖）：

```bash
cd <项目目录>
pip install .        # 用 pyenv 的话，装完执行一次 pyenv rehash
```

所有命令都支持 `--json`（放命令前或后都可以），Agent 调用时建议加上。

## 凭据（只需一次）

CLI 需要 Tripo 的 session cookie 才能换 JWT。**不需要浏览器常驻**：cookie 约 30 天有效，
CLI 每次调用会用 cookie 自动续期 15 分钟的 JWT。

```bash
tripocli account add --cookie "ory_kratos_session=..."   # 添加账号（粘贴浏览器 cookie）
tripocli account list                                     # 多账号查看/切换
tripocli serve --open                                     # 网页版账号管理（看积分/有效期）
# 也可用环境变量：export TRIPO_COOKIE="ory_kratos_session=..."
```

cookie 获取：浏览器 DevTools → Network → 任意 `api.tripo3d.ai` 请求 → Request Headers → 整条 `Cookie`。
若命令报 `no-credentials`，按上面的 `account add` 提供 cookie 即可。

## 常用命令

```bash
# 账户
tripocli --json balance
tripocli --json quota
tripocli --json assets --size 10

# 文生图（参考图生成，默认 --amount 1 每次只出 1 张以节省额度；人形角色建议加 --t-pose）
tripocli --json img -p "<提示词>" --amount 1 --t-pose --wait -o /abs/path/refs
tripocli --json imgs --size 5
tripocli --json imgmv -i /abs/path/ref.png --wait -o /abs/path/views

# 文生 3D（⚠️ 游戏场景务必加 --face-limit 控制面数或用 --smart-mesh，避免默认 200 万面撑爆显存！）
tripocli --json text -p "<提示词>" --face-limit 15000 --wait -o /abs/path/out.glb
tripocli --json text -p "<提示词>" --smart-mesh --face-limit 20000 --wait -o /abs/path/out.glb

# 图生 3D / 导入模型
tripocli --json image -i /abs/path/photo.png --face-limit 25000 --wait -o /abs/path/out.glb
tripocli --json import -i /abs/path/my_model.glb --wait -o /abs/path/normalized.glb

# 多视角（必须 4 张：前/左/右/后）
tripocli --json multiview --front f.png --left l.png --right r.png --back b.png --wait -o /abs/path/mv.glb

# 批量图生 3D（多结果，-o 传目录）
tripocli --json batch -i a.png,b.png --wait -o /abs/path/outdir

# 后处理（作用于已有项目，需要 project_id）
tripocli --json remesh  -p <project_id> --face-limit 10000 --wait -o low.glb
tripocli --json rig     -p <project_id> --type biped --spec mixamo --wait -o hero_rigged.glb
tripocli --json animate --list
tripocli --json animate -p <project_id> --preset idle --wait -o anim_idle.glb
tripocli --json motion  -p "让角色挥手打招呼" --duration 5 --project <project_id> --wait -o anim_wave.glb
tripocli --json segment -p <project_id> --wait
tripocli --json stylize -p <project_id> --style clay --wait
tripocli --json texture -p <project_id> --resolution 2K --wait
tripocli --json pbr     -p <project_id> --wait
tripocli --json upscale -p <project_id> --wait
tripocli --json uv      -p <project_id> --wait
tripocli --json fill    -p <project_id> --parts all --wait
tripocli --json edit    -p <project_id> --bbox "-1,-1,-1,1,1,1" --face-limit 8000 --wait

# 导出 / 下载 / 本地体检与减面 / 查询 / 取消 / 重命名
tripocli --json export   -p <project_id> -f glb --wait -o model.glb
tripocli --json download --operator <operator_id> -o model.glb
tripocli --json inspect  /abs/path/model.glb
tripocli --json optimize /abs/path/in.glb -o /abs/path/out.glb --faces 15000
tripocli --json optimize /abs/path/in.glb --lods
tripocli --json task status <operator_id>
tripocli --json project <project_id>
tripocli --json cancel --operator <operator_id> --type remesh
tripocli --json rename -p <project_id> --name "New Name"
```

## 生成类通用参数

- `-m/--model`：`P2.0` / `P1.0`（智能网格）、`H3.1` / `v3.0` / `v2.5`（高精度）
- `--face-limit`：面数上限（智能网格默认 25000，高精度默认 2000000）
- `--quad`：四边面（智能网格默认开启）
- `--count 1|2|4`：候选数量
- `--no-texture` / `--no-pbr` / `--no-delight`
- `--texture-quality standard|detailed`、`--geometry-quality standard|detailed`
- `--t-pose`、`--visibility shareable|private`

## 重要约束

1. **后处理算子会新建 operator**：同一项目必须等上一个算子 `success` 后才能做下一个，否则报
   `2021 the status of task is not success`。用 `--wait`，或换项目。
2. **图片自动走「上传 S3 + 审核」**：`image` / `multiview` / `batch` 内部已处理，无需手工调用审核接口。
3. **智能 UV 需要低模**：模型须先 `remesh` 到 ≤8 万三角面才能使用。
4. 生成的模型 URL 带签名且有时效，需要长期保存时用 `--wait -o` 落盘。

## 游戏与 3D 大场景构建必读规范（防卡顿 / 防陷地 / 骨骼动画）

当用 `tripocli` 生成多个资产组装游戏场景（Three.js / Godot / Unity / Unreal）时，**必须遵守以下 5 条铁律**：

1. **严控面数（防止 6000 万面撑爆显存卡顿）**：
   - 高精度模式（`v3.1`）默认 `face_limit=2,000,000`，单个建筑/树木可达 **70 万～95 万三角面**！若在主城里克隆几十份，总面数会突破 **6,000 万面** 导致严重掉帧。
   - **源头控面（首选，省积分）**：生成建筑/树木/道具时直接传 `--face-limit 15000`（或加 `--smart-mesh` 走 P2.0 智能网格四边面低模）。
   - **本地真减面（已有高模救火 / 生成多级 LOD，0 积分秒级完成）**：
     入场前先用 `tripocli inspect *.glb` 检查面数，再用内置的 `tripocli optimize` 一键减面压缩（内部已自动区分静态模型 `--error 0.06` 与骨骼角色 `--error 0.02`，避免直接调 `gltf-transform optimize` 时默认 `--simplify-error 0.0001` 导致只压缩不减面的坑）：
     ```bash
     tripocli inspect /abs/path/assets/*.glb
     tripocli optimize in.glb -o out.glb --faces 15000
     tripocli optimize in.glb --lods
     ```
2. **模型接地封装（防止建筑/树木半截埋入地下）**：
   - Tripo 导出的 GLB 模型原点位于**几何中心**（`y ∈ [-H/2, +H/2]`），不在底部。
   - 若直接修改模型自身的 `obj.position.y -= box.min.y` 后又在外部调用 `obj.position.set(x, 0, z)`，会把 `y` 重置回 `0`，导致所有房屋、城门、树木**整整下半截 50% 埋进地里**！
   - **正确做法**：将缩放并偏移好底部高度（`rawObj.position.y = -box.min.y`）的模型包裹进一个外层 `const wrap = new THREE.Group()`，使 `wrap` 的 `(0,0,0)` 严格位于模型底部中心，外部只移动 `wrap.position.set(x, groundY, z)`。
3. **骨骼动画加载（本体 Mesh + 纯骨骼轨道分离架构）**：
   - `tripocli rig` 产出的 GLB 含完整网格与 65 根骨骼（`SkinnedMesh`）；
   - `tripocli animate`（`retarget_model`）产出的 GLB **仅含 65 根骨骼的动画轨道（约 100～500KB），不含任何 Mesh**！
   - 在引擎中应以 `rig` 导出的 `hero.glb` 作为渲染网格，再加载各个 `anim_*.glb` 提取其中的 `gltf.animations` 挂到同一个 `AnimationMixer(heroModel)` 上播放。
4. **带骨骼角色（SkinnedMesh）的包围盒测量**：
   - Three.js 的 `Box3.setFromObject()` 对 `SkinnedMesh` 默认按绑定初始网格算，不含骨骼根变换，会导致算出的角色高度翻倍或悬空。应遍历 `o.isBone` 的骨骼世界坐标 `o.getWorldPosition()` 计算角色真实高度与脚底 `min.y`。
5. **渲染管线与阴影减负**：
   - 场景中有上百个建筑/道具时，只让主要建筑和角色开启 `castShadow = true`，**关闭复杂模型之间的 `receiveShadow`**（仅地面、广场、台阶开启 `receiveShadow = true`），并将高分屏像素比限制在 `Math.min(devicePixelRatio, 1.5)`，可让 WebGL 稳定跑满 **120 FPS**。

## 详细文档

命令全集与接口契约见 [README.md](./README.md) 与 [TRIPO_API_SPEC.md](./TRIPO_API_SPEC.md)。