Mrpzx
977f97995a
覆盖文生 3D、图生 3D、多视图、批量生成，以及重拓扑、绑定、动画、智能分割、 纹理、PBR、智能 UV、部件补全、格式导出与下载。 代码组织：一个功能一个模块（tripo/features/），入口薄壳 tripocli.py。
207 lines
9.4 KiB
Markdown
207 lines
9.4 KiB
Markdown
# 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)。
|