Mrpzx/tripocli
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
671fe2f55a2f5e9a59821bf0c15631f9cfac086d
tripocli/README.md
T

11 KiB
Raw Blame History

tripocli

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

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

一、安装与更新

1. 一行命令安装（推荐，免装 Python）

自动识别系统与架构，拉取最新 Release 的独立可执行文件并装进 PATH：

curl -fsSL https://git.usetoks.com/Mrpzx/tripocli/raw/branch/main/install.sh | sh

安装到 /usr/local/bin（可写时）或 ~/.local/bin。装完直接可用：

tripocli --version
tripocli --help

可选参数（环境变量）：

# 指定版本
curl -fsSL .../install.sh | TRIPOCLI_VERSION=v2.0.0 sh
# 指定安装目录
curl -fsSL .../install.sh | TRIPOCLI_INSTALL_DIR=~/.local/bin sh

也可以手动下载：到 Releases 取对应平台的文件，chmod +x 后直接运行。

平台 文件
Linux x86_64 tripocli-<版本>-linux-x86_64
macOS（Apple Silicon） tripocli-<版本>-macos-arm64

Windows 暂无独立可执行文件（PyInstaller 无法跨平台编译），请用下面的 pip 方式。

2. 用 pip 安装（需要 Python ≥ 3.8）

# 直接从 Gitea 仓库安装，无需先克隆
pip install "git+https://git.usetoks.com/Mrpzx/tripocli.git"

# 或在克隆后的项目目录里安装
cd <项目目录>
pip install .
pyenv rehash      # 使用 pyenv 时执行一次以刷新命令路径
tripocli --version

3. 免安装直接运行

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

<项目目录>/tripocli --version

4. 更新

  • 用安装脚本装的：重跑一遍安装命令即可（自动取最新版本）；
  • 用 pip 装的：pip install -U "git+https://git.usetoks.com/Mrpzx/tripocli.git"；
  • 从源码跑且已 pip install . 的，可用内置命令从源码更新：
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。

# 添加账号（交互式隐藏粘贴或命令行直接传入）
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. 游戏角色与资产标准流程

# 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. 账户与资产查询

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

3. 生成命令

# 文生图（支持模型: 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. 后处理、导出与任务管理

# 拓扑与网格处理
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 压缩）： 
      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，代码结构与维护说明详见 AGENTS.md。

Reference in new issue View Git Blame Copy Permalink