# tripocli

面向 AI Agent 与开发者的 Tripo AI 3D 生成命令行工具。纯 Python 3 标准库实现，零第三方依赖。

支持：文生图、文生 3D、单图/多视角/批量图生 3D、模型导入，以及重拓扑、骨骼绑定、动作预设重定向、文字生成动作、智能分割、3D 风格化、纹理生成与放大、PBR、智能 UV、部件补全、网格编辑、格式转换导出与多账号管理。

---

## 一、安装与更新

### 1. 安装为全局命令（推荐）

```bash
cd <项目目录>
pip install .
pyenv rehash      # 使用 pyenv 时执行一次以刷新命令路径
tripocli --version
```

### 2. 免安装直接运行

无需 `pip`，直接运行仓库内的入口脚本：

```bash
<项目目录>/tripocli --version
```

### 3. 更新

修改或拉取新源码后，一条命令重装全局 CLI：

```bash
tripocli update              # 从项目源码更新全局命令
tripocli update --check      # 查看当前源码路径与版本状态
```

---

## 二、账号配置

只需提供一次浏览器 Cookie（`ory_kratos_session` 约 30 天有效），CLI 会在每次调用时自动换取并续期 JWT，日常运行无需打开浏览器。

Cookie 获取方式：浏览器登录 `studio.tripo3d.ai` → DevTools (`F12`) → Network → 任意 `api.tripo3d.ai` 请求 → 复制 Request Headers 中的 `Cookie`。

```bash
# 添加账号（交互式隐藏粘贴或命令行直接传入）
tripocli account add
tripocli account add --name work --cookie "ory_kratos_session=..."
tripocli account add --cookie-file cookie.txt

# 多账号查看与切换
tripocli account list
tripocli account use work
tripocli account show work
tripocli account remove work

# 单条命令指定账号（多账号默认在额度不足时自动切换，可用 --no-fallback 关闭）
tripocli --account work balance
tripocli --no-fallback text -p "a wooden crate" --wait -o crate.glb

# 本地网页版账号管理（可视化添加/校验 Cookie、查看实时积分与到期时间）
tripocli serve --open        # 默认监听 http://127.0.0.1:8765/

# 无配置文件场景（服务器 / CI 环境变量）
export TRIPO_COOKIE="ory_kratos_session=..."
```

> 账号凭据保存在 `~/.tripo/accounts.json`（权限 `600`），更新代码不会影响已配置的账号。

---

## 三、命令速查

所有命令均支持 `--json`（可放在子命令前或后）输出标准 JSON，便于脚本与 Agent 解析。

### 1. 游戏角色与资产标准流程

```bash
# 1) 文生图：生成参考图（默认 --amount 1 每次 1 张；人形角色建议加 --t-pose）
tripocli img -p "full-body T-pose anime female knight, white background" --t-pose --wait -o ./refs

# 2) 图生 3D（建议加 --face-limit 控制面数，或加 --smart-mesh 生成四边面低模）
tripocli image -i ./refs/image_0.png --face-limit 25000 --wait -o hero_mesh.glb

# 3) 绑定骨骼（支持 mixamo / actorcore / unreal / unity / vrm 五种预设）
tripocli rig -p <project_id> --type biped --spec mixamo --wait -o hero_rigged.glb

# 4) 动作预设重定向（97 种人形动作预设）
tripocli animate --list
tripocli animate -p <project_id> --preset idle --wait -o anim_idle.glb
tripocli animate -p <project_id> --preset walk --wait -o anim_walk.glb
tripocli animate -p <project_id> --preset run  --wait -o anim_run.glb
tripocli animate -p <project_id> --preset slash --wait -o anim_slash.glb

# 5) 文字生成动作（AI 动画）：一句话生成自定义动作并套用到角色
tripocli motion -p "让角色挥手打招呼" --duration 5 --project <project_id> --wait -o anim_wave.glb
```

### 2. 账户与资产查询

```bash
tripocli balance                 # 积分余额与会员状态
tripocli whoami                  # 当前身份与 Token 有效期
tripocli quota                   # 免费试用额度
tripocli assets --size 10        # 列出已生成的 3D 模型项目
tripocli imgs --size 10          # 列出已生成的参考图资产
tripocli project <project_id>    # 查看项目详情、模型直链与已重定向的动作列表
```

### 3. 生成命令

```bash
# 文生图（支持模型: nano-banana-2 / nano-banana-pro / gpt-image-2 / gpt-image-2.5 / midjourney）
tripocli img -p "a stylized treasure chest, game asset" --amount 1 --scale 1:1 --resolution 2K --wait -o ./refs
tripocli img --templates         # 查看官方提示词模板

# 单图转 4 视角参考图
tripocli imgmv -i ./refs/image_0.png --wait -o ./views

# 文生 3D
tripocli text -p "medieval house" --face-limit 15000 --wait -o house.glb
tripocli text -p "wooden barrel" --smart-mesh --wait -o barrel.glb

# 单图生 3D / 多视角生 3D / 批量图生 3D
tripocli image -i ./photo.png --face-limit 15000 --wait -o model.glb
tripocli multiview --front f.png --left l.png --right r.png --back b.png --wait -o mv.glb
tripocli batch -i a.png,b.png,c.png --face-limit 15000 --wait -o ./out

# 导入本地模型（glb/obj/fbx/stl ≤150MB）转为云端项目以便继续绑定/后处理
tripocli import -i ./my_model.glb --wait -o imported.glb
```

**生成类通用参数**：
- `-m/--model`：`P2.0` / `P1.0`（智能网格）、`H3.1` / `v3.0` / `v2.5`（高精度）
- `--smart-mesh`：开启智能网格模式（四边面低模，默认 25,000 面）
- `--face-limit <N>`：面数上限（高精度默认 2,000,000；**用于实时游戏场景时建议设为 `10000`～`25000`**）
- `--quad`：输出四边面拓扑
- `--count 1|2|4`：一次生成候选数量（默认 1）
- `--t-pose`：人形角色输出标准 T-Pose
- `--no-texture` / `--no-pbr` / `--no-delight`：关闭贴图、PBR 或去光处理
- `--texture-quality standard|detailed`、`--geometry-quality standard|detailed`

### 4. 后处理、导出与任务管理

```bash
# 拓扑与网格处理
tripocli remesh  -p <pid> --face-limit 10000 --wait -o low.glb
tripocli segment -p <pid> --wait -o segmented.glb
tripocli fill    -p <pid> --parts all --wait -o filled.glb
tripocli edit    -p <pid> --bbox "-1,-1,-1,1,1,1" --face-limit 8000 --wait
tripocli uv      -p <pid> --wait -o uv.glb

# 材质与风格化
tripocli texture -p <pid> --resolution 2K --wait -o tex.glb
tripocli upscale -p <pid> --wait -o upscaled.glb
tripocli pbr     -p <pid> --wait -o pbr.glb
tripocli stylize -p <pid> --style clay --wait -o clay.glb

# 骨骼与动画
tripocli rig     -p <pid> --type biped --spec mixamo --wait -o rigged.glb
tripocli rig     -p <pid> --check-only
tripocli animate -p <pid> --preset walk --wait -o anim_walk.glb
tripocli motion  --list

# 格式转换导出（支持 glb / fbx / obj / stl / usdz / 3mf）与下载
tripocli export   -p <pid> -f glb --wait -o model.glb
tripocli download --operator <operator_id> -o model.glb

# 本地游戏资产体检与减面压缩（纯本地运行，0 积分）
tripocli inspect  ./assets/*.glb                           # 查看面数、包围盒、骨骼、动画名与告警
tripocli optimize house.glb -o house_low.glb --faces 15000 # 保 UV 真减面 + Draco 压缩
tripocli optimize hero.glb --in-place --faces 45000        # 带骨骼角色原地减面（自动保护五官与关节）
tripocli optimize house.glb --lods                         # 一键生成 lod0 / lod1 / lod2 三级细节模型

# 任务进度、取消与项目重命名
tripocli task status <operator_id>
tripocli task wait <operator_id> -p <pid> -o out.glb
tripocli cancel --operator <operator_id> --type remesh
tripocli rename -p <pid> --name "My Hero"
```

---

## 四、使用须知与游戏场景建议

1. **同一项目的后处理需串行执行**：
   后处理算子（`remesh` / `rig` / `pbr` / `texture` / `uv` 等）必须等该项目上一个任务状态变为 `success` 后才能提交下一个，否则服务端会返回 `2021`。建议直接加上 `--wait`。
2. **游戏场景务必控制面数（防卡顿）**：
   - 高精度模式默认上限为 200 万面（单个建筑/树木可达 70 万～90 万三角面），直接在游戏场景中批量摆放会导致严重卡顿。
   - **生成时控面**：生成建筑、树木、道具时建议直接传 `--face-limit 15000` 或 `--smart-mesh`。
   - **已下载高模本地减面与压缩（0 积分）**：直接运行内置的 `tripocli inspect` 与 `tripocli optimize`（底层自动为静态模型与骨骼角色匹配最佳误差容忍度并执行 Draco 压缩）：
     ```bash
     tripocli inspect ./assets/*.glb
     tripocli optimize in.glb -o out.glb --faces 15000
     tripocli optimize in.glb --lods
     ```
3. **角色本体与动作文件合并加载**：
   - `tripocli rig` 导出的 GLB 包含完整角色网格与骨骼（`SkinnedMesh`）；
   - `tripocli animate` 导出的 GLB **仅包含 65 根骨骼的动画关键帧轨道（约 100～500KB），不含网格**。在 Three.js / Godot / Unity 中加载 1 份 `rig` 本体模型，再将多个 `animate` 导出的动画轨道挂载到同一角色的动画控制器上即可切换动作。
4. **模型原点与格式转换**：
   - Tripo 导出的 GLB 原点位于模型**几何中心**（而非底部），在引擎中摆放并缩放后，需按包围盒最低点（`-box.min.y`）用外层容器对齐地面，避免在设置 `(x, 0, z)` 坐标时把模型下半截埋入地下。
   - 部分旧项目或经过特定后处理的项目默认直链为 `.fbx`，如需在网页或引擎中按 `.glb` 加载，执行 `tripocli export -p <pid> -f glb --wait -o out.glb` 即可。

---

底层 HTTP 接口协议与字段契约详见 [TRIPO_API_SPEC.md](./TRIPO_API_SPEC.md)，代码结构与维护说明详见 [AGENTS.md](./AGENTS.md)。