Tripo CLI：让 AI 帮你把文字和图片变成 3D 模型

Tripo CLI 为 AI Agent 而设计，让 3D 创作像聊天一样简单。无论是在 Codex、Claude Code、Cursor 等 AI 编码工具中，还是直接使用 CLI，只需一句自然语言描述、一张图片或一个现有模型，即可生成或转换 3D 模型、动画等资产。CLI 会自动完成整个流程，无需理解 API、模型版本或复杂参数。

我该用 CLI 还是 API？

Tripo 有两种使用方式，先花 10 秒确认哪种最适合你：

产品	适合谁	入口
Tripo CLI（本页）	小白用户，借助主流 Vibe Coding 工具快速调用 AI 3D 能力	继续往下读
Tripo API	专业开发者，将 AI 3D 能力集成至网站、App 或自有业务系统	快速开始

拿不准的话，就按本页先试一次：安装是免费的，只有真正生成模型时才消耗积分。

安装并登录（两种方式，选一种）

以下安装方式二选一

方式一：让 AI 帮我安装（推荐）

如果你正在使用 Cursor、Claude Code、Codex 等可以操作终端的 AI 助手，这是最省心的方式。把下面的提示词完整复制并发送给它：

请帮我安装并配置 Tripo CLI，同时解释每一步。先确认本机已安装 Node.js 20 或更高版本，再执行 npm install -g tripo-cli。如果当前是 Windows PowerShell 且提示禁止运行脚本，请先执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（不要用管理员身份），然后再重试。登录前先问我账号在哪个站：海外站 developers.tripo3d.ai（ov），还是国内站 developers.tripo3d.com（cn），不要根据语言或登录方式猜测。根据我的回答运行 tripo login --region ov 或 tripo login --region cn，把授权网址和一次性验证码告诉我，并保持命令运行，等待我在浏览器中完成授权；不要让我把 API Key 粘贴到聊天中。最后运行 tripo doctor，并告诉我认证、网络和余额检查是否通过。

接下来会发生什么：

AI 检查电脑环境，缺 Node.js 时会先带你装好；
AI 运行安装命令；
轮到你：确认账号站点，打开 AI 提供的授权网址，输入或核对终端里的一次性验证码后授权（这一步必须本人完成，不要把任何密钥发给 AI）；
AI 运行 tripo doctor 检查，全部通过就安装完成了。

完成后直接跳到下一节“生成你的第一个 3D 模型”。

遇到问题？AI 卡住或报错了

把终端里的报错原样发给 AI，让它继续处理，绝大多数问题它都能解决；
登录没有完成：重新打开登录页面，核对终端里显示的验证码后再确认；
实在不行，改用下面的“方式二：我自己安装”，一共只有三条命令。

方式二：我自己安装

不使用 AI 助手也完全没问题，全程只有三条命令。

第 1 步：安装 Tripo CLI

这条命令会把 tripo 命令安装到电脑里：

Bash

npm install -g tripo-cli

正常情况下，安装进度结束后没有红色报错，就说明装好了。

已经安装过？运行 tripo update --check 检查更新，再用 tripo update 安装最新版本。

遇到问题？找不到 npm，或提示权限不足

提示找不到 npm：说明 Node.js 还没装好。前往 Node.js 官网安装当前 LTS 版本（20 或更高），装完后重新打开终端再运行一次；
macOS 提示权限不足（EACCES）：改用 sudo npm install -g tripo-cli，按提示输入电脑密码；
Windows 提示“禁止运行脚本”：在 PowerShell 中运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（不需要管理员权限），重新打开终端后再试。更多示例见下文「Windows / PowerShell」。

第 2 步：登录 Tripo 账号

国内站 developers.tripo3d.com 账号使用支付宝，运行：

Bash

tripo login --region cn

如果账号属于海外站 developers.tripo3d.ai（Stripe），改用 tripo login --region ov。在交互终端直接运行 tripo login，则会先询问账号站点。

浏览器会自动打开所选站点的授权页面（还没有账号就先在页面上注册一个）。按页面要求输入或核对终端里的一次性验证码，再确认授权。 授权后 CLI 会自动接收 Key，终端会提示已登录。

显示验证码的 Tripo CLI 浏览器设备授权页面

遇到问题？浏览器没打开，或登录没有完成

登录没有完成：重新运行 tripo login，在打开的页面里核对终端显示的验证码后确认；
浏览器一直没有反应：把终端里显示的网址手动复制到浏览器打开；
浏览器授权暂时不可用：交互终端会改为打开 API Key 页面；AI Agent 等非交互环境可同时设置 TRIPO_API_KEY 和正确的 TRIPO_REGION、运行 tripo login --key tsk_...，或换到交互终端重试，见下方“备用登录方式与区域说明”。

第 3 步：检查一切是否就绪

Bash

tripo doctor

它会依次检查登录状态、网络和积分余额。三项全部通过，安装就完成了。

遇到问题？某一项检查没通过

认证未通过：登录没有完成，重新运行 tripo login 再登录一次；
网络未通过：确认电脑能正常打开网页；公司或校园网络可能需要配置代理；
余额未通过：当前积分不足，此时不会开始任何生成，也不会扣费。运行 tripo topup 打开充值页面。

备用登录方式与区域说明（浏览器登录不可用时再看）

已有 API Key 时，可以运行 tripo login --key tsk_... 直接登录，或同时设置 TRIPO_API_KEY 和对应账号的 TRIPO_REGION（ov 或 cn）；
API Key 相当于账号凭证，不要粘贴到聊天、代码、截图或日志中；
tripo login --key tsk_... 会探测两个区域并保存可用区域；直接设置 TRIPO_API_KEY 不会进行这一步探测。浏览器授权前需要明确账号站点：海外站选 ov，国内站选 cn；
AI Agent 等非交互环境在没有 Key 时必须指定 --region。CLI 会输出授权网址和一次性验证码，并等待本人在浏览器授权；应先询问账号站点，不根据语言或登录方式推断。

Windows / PowerShell

本页命令以 Bash 为例。它们在 Windows 上同样可用，但 PowerShell 对部分符号的解析与 Bash / cURL 不同——在 PowerShell 中请复制下面的示例，不要直接粘贴 Bash 代码块。

允许运行 tripo 命令

npm 会安装 tripo.ps1 包装脚本，PowerShell 的默认执行策略会拦截它：

PowerShell

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

重新打开终端后再运行 tripo doctor。这一步不需要管理员权限。如果希望不改策略，改用命令提示符（cmd.exe），其中可以直接运行 tripo。

给 @last 和带逗号的参数加引号

PowerShell 会把 @name 当成特殊语法，把 , 当成数组分隔符：

PowerShell

tripo make "一只可爱的低多边形狐狸"
tripo view '@last'
tripo make hero.glb --then 'texture,rig'
tripo make '@last' --then 'convert:fbx'

在命令提示符中不需要这些额外引号。

设置环境变量

PowerShell

# 仅当前窗口有效
$env:TRIPO_API_KEY = "tsk_..."
$env:TRIPO_REGION = "cn"
$env:TRIPO_PROFILE = "work-cn"

# 为当前 Windows 用户持久保存
[System.Environment]::SetEnvironmentVariable("TRIPO_API_KEY", "tsk_...", "User")
[System.Environment]::SetEnvironmentVariable("TRIPO_REGION", "cn", "User")

配置和历史默认保存在 %USERPROFILE%\.tripo（即 Windows 上的 ~/.tripo）。

JSON 管道

PowerShell

# PowerShell 7 或更高版本（推荐）
tripo make cat.png --json | tripo model texture --json | tripo anim rig --json

# Windows PowerShell 5.1：先把输出接到变量里
$json = tripo make cat.png --json --no-open
$json | tripo model texture --json

如果中文提示词出现乱码，请使用 Windows Terminal，或先运行 chcp 65001。

生成你的第一个 3D 模型

第 1 步：用一句话生成

引号里的文字就是提示词，把它换成你想要的任何物体：

Bash

tripo make "一只可爱的低多边形狐狸"

命令运行期间保持终端打开。Tripo CLI 会自动选择合适的生成流程和模型、等待任务完成，并把文件下载到当前目录的 tripo-out 文件夹。整个过程通常几分钟内结束，消耗账户中的少量积分。

遇到问题？生成没有开始，或中途失败

提示积分不足：本次模型还没有开始生成，不会扣费。运行 tripo topup 充值后重试；
提交时遇到网络错误或 HTTP 5xx：任务可能已经在服务端创建。先用 tripo balance 查看冻结积分，并到控制台确认，再决定是否重新提交；已有任务 ID 时用 tripo task watch <task-id> --download 继续等待；
等待超时：任务可能仍在运行，成功后仍会计费。用 tripo task watch <task-id> --download 继续等待，不要重复运行 make，也不要用 redo 恢复超时任务；
任务失败：已扣的积分会自动退回，换一个描述再试一次。

第 2 步：打开预览

Bash

tripo view @last

@last 表示“最近一次任务”。浏览器会打开一个可以拖动旋转的 3D 预览——看到你的模型，就成功了！在 PowerShell 中请写成 tripo view '@last'。

成功之后，你现在拥有什么

文件在哪：tripo-out 下多了一个新文件夹，里面有下载好的 3D 模型文件和记录任务参数的 task.json；如果服务端提供预览图，还会有 preview.png。
再次打开：随时运行 tripo view @last；也可以用 tripo view 文件路径 打开任意模型文件。
花了多少：运行 tripo balance 查看积分余额。
不想记命令：直接运行 tripo 会打开带引导的交互菜单，登录、生成、预览、充值都能在里面完成。
下一步：用图片生成（下一节）、让 AI 助手替你操作（“让 AI 编码 Agent 深度使用 CLI”一节），或批量处理（“现成场景与流水线”一节）。

用图片或已有模型生成

文字生成跑通后，还可以把本地图片或模型文件作为输入。下面的 concept.png、front.png、hero.glb 都是示例文件名，请替换成你自己的文件路径：

Bash

tripo make concept.png --for print
tripo make front.png back.png
tripo make hero.glb --then texture,rig
tripo make @last --then convert:fbx

第 1 条：把一张概念图变成适合 3D 打印的模型；
第 2 条：用正、反两张图片一起生成，细节更准确；
第 3 条：给已有模型补贴图并绑定骨骼；
第 4 条：把最近一次的结果转换成 FBX 格式。

让 AI 编码 Agent 深度使用 CLI

如果你用的是 Codex，请先看 Tripo 3D Codex 插件：用日常语言说话即可，不用自己敲 CLI 命令。

不使用 AI 编码 Agent 可以跳过本节。npm 包内置一份 Agent Skill，包含命令参考、场景方案和错误恢复说明，帮助 Agent 正确使用 CLI。让 Agent 运行下面的命令，即可在终端中输出完整说明或单个主题：

Bash

tripo docs --llm
tripo docs --topic commands/make
tripo docs --topic examples/game-asset

Skill 内置文件一览

skill/
├── SKILL.md
├── common-errors.md
├── commands/
│   ├── account.md
│   ├── batch.md
│   ├── generate.md
│   ├── make.md
│   ├── process.md
│   ├── task.md
│   └── view.md
└── examples/
    ├── animation.md
    ├── ar-web.md
    ├── film.md
    ├── game-asset.md
    ├── pipes.md
    └── print.md

命令参考

不需要记住整张表：新手日常只用得到 tripo（交互菜单）、tripo make（生成）、tripo view（预览）和 tripo doctor（检查环境）四个命令，其余命令在有明确需求时再展开查询。

展开完整命令表与通用参数

命令	作用
`tripo make <input...>`	用一个命令完成生成、处理和下载
`tripo ai [description]`	规划任务、确认方案并执行
`tripo view [task\|file]`	在浏览器中打开本地交互式 3D 预览
`tripo redo [task]`	使用新种子重新执行请求
`tripo login / logout / whoami / use`	授权并切换命名账号配置
`tripo topup / balance / usage`	打开对应区域的充值页并查询积分
`tripo generate <endpoint>`	明确调用全部 8 个生成接口
`tripo model / anim / mesh <step>`	执行精修、贴图、绑骨、转换、分割等处理
`tripo mesh decimate [input]`	减面；v3.0 支持在同一任务中展 UV
`tripo mesh uv [input]`	智能展 UV，并映射原贴图、骨骼和动画
`tripo task get/list/watch`	查询、列出或等待任务
`tripo history [--limit <n>]`	查看最近的本地任务历史
`tripo files upload <path>`	上传文件并返回 `file_token`
`tripo batch run <manifest.yaml>`	以并发、重试和断点续跑执行批量流水线
`tripo config / doctor`	管理设置并诊断本地环境
`tripo update [--check]`	安装最新 CLI，或仅检查更新
`tripo docs [--topic <topic>]`	输出内置 Agent 与命令文档
`tripo mcp`	以 MCP Server 方式运行 CLI
`tripo completion <shell>`	为 Bash、Zsh 或 Fish 生成自动补全（不支持 PowerShell）

make、ai、generate 命令，以及 model、anim、mesh 下的处理子命令，支持 -o/--out、--no-wait、--no-download、--name、--timeout、--notify，以及可重复的 --param key=value。全局自动化参数包括 --json、--yes、--quiet、--no-open 和 --profile。

现成场景与流水线

这是进阶内容，第一次生成时不需要。CLI 内置 7 个场景预设，通过 --for 预设名 一次性套用常用参数和后处理步骤：

game-mobile · game-pc · film · print · ar-web · anim · toy

Bash

# 移动游戏资产：低模生成、贴图并转换为 FBX
tripo make "科幻补给箱" --for game-mobile

# 3D 打印资产：封闭网格、STL 和平底处理
tripo make "国际象棋骑士" --for print

# 显式后处理链
tripo make cat.png --then texture,rig,convert:fbx

# 使用 NDJSON 管道组合同一处理链
tripo make cat.png --json | tripo model texture --json | tripo anim rig --json

# 可断点续跑的批量处理
tripo batch run assets.yaml --concurrency 2

重拓扑与展 UV

decimate 默认仍使用 v2.0。需要新版重拓扑时指定 v3.0；--smart-uv 可在同一任务中展 UV，仅支持 v3.0（带此参数但省略 --model 时，会自动选择 v3.0）。

Bash

tripo mesh decimate hero.glb --model v3.0 --face-limit 5000 --smart-uv
tripo mesh uv hero.glb

独立的 uv 步骤会把原贴图、骨骼和动画映射到新 UV 布局，并返回 UV 展开图。输入不得超过 80,000 个等效三角面（一个四边面按两个三角面计）；更大的模型先减面，例如 tripo make hero.glb --then decimate:20000,uv。PowerShell 中将处理链写成 'decimate:20000,uv'。

凡是接受任务 ID 的位置，都可以使用 @last、@2 和 @name 等任务引用。

多账号与区域

如果只使用一个 Tripo 账号，可以跳过本节。凭证保存在命名配置（profile）中，登录第二个账号不会覆盖第一个账号的 Key：

Bash

tripo login --region cn --profile personal-cn
tripo login --region cn --profile work-cn
tripo use personal-cn
tripo whoami
tripo make "一只狐狸" --profile personal-cn
tripo logout

每个配置分别保存自己的 Key 和区域。环境变量 TRIPO_PROFILE 可为当前环境选择配置；TRIPO_API_KEY 优先于配置中保存的 Key，但不会自动识别其区域，直接通过环境变量提供 Key 时应同时设置对应的 TRIPO_REGION。

为每个账号选择对应区域。tripo topup 会打开当前配置所属区域的充值页：海外站为 /billing，国内站为 /billing/recharge。

AI 编码 Agent 注意事项

普通用户可以跳过本节。这些规则用于帮助 Agent 正确等待任务并读取机器可读的输出。

tripo make 和 tripo task watch 是阻塞命令。应等待进程结束，不要重复实现轮询。
使用 --json 时，大多数一次性命令会向 stdout 输出一行最终 JSON；tripo task watch --json 则会以 NDJSON 流式输出进度事件，最后输出最终结果。
如果存在 preview.png，应在继续流水线或执行 tripo redo 前先检查它。
不要编造参数或强制使用旧模型版本。通过 tripo docs --topic ... 查询支持的参数。
低模意图或面数预算不超过 20,000 时选择 tripo-p1，其他任务默认使用 tripo-v3.1。
tripo-p2 为 Preview 模型，需要显式指定 --model tripo-p2。需要低模四边面时再加 -p quad=true，四边面输出为 FBX，P1 不支持四边面。使用 CLI 模型别名即可，CLI 会转换为 API 所需的带日期版本值。
可用 tripo make "一个低多边形机器人" --model tripo-p2 --dry-run 预览计划；不会上传、创建任务或消耗积分。
创建任务仅在 HTTP 429 时自动重试。网络错误、超时或 HTTP 5xx 可能导致提交结果不确定，重新提交前先检查账号状态。

展开退出码表

退出码	含义
`0`	成功
`1`	意外或内部错误
`2`	用法或参数错误
`3`	认证错误
`4`	积分不足
`5`	内容安全策略拒绝
`6`	任务失败（积分退回），或等待超时（任务可能仍在运行，应继续查询）
`7`	网络错误
`8`	资源不存在
`9`	触发限流；应退避后重试

自动化环境变量

日常交互使用不需要配置环境变量，它们主要用于 CI、脚本和进阶 Agent 工作流。切记：不要把 API Key 提交到代码仓库、粘贴进文档，或包含在截图和日志中。

国内区域及自定义 API 地址不发送 CLI 使用统计。海外官方 API 默认启用匿名使用统计，以随机安装 ID 记录命令结果和任务元数据，包括模型与任务类型、积分与耗时、错误类别、输出格式与文件数、Agent 来源；不包含提示词、文件路径、输入素材、API Key 或下载链接。使用海外官方 API 时，设置 TRIPO_ANALYTICS_ENABLED=0 可关闭统计。

展开环境变量表

变量	用途
`TRIPO_API_KEY`	优先于保存的 Key，但不会识别区域；脚本中应同时设置正确的 `TRIPO_REGION`
`TRIPO_PROFILE`	命名账号配置，等价于 `--profile`
`TRIPO_REGION`	以 `ov` 或 `cn` 覆盖 API 请求区域；非交互浏览器授权仍须显式传入 `login --region`
`TRIPO_API_BASE_URL`	覆盖 API 地址
`TRIPO_PLATFORM_BASE_URL`	覆盖平台地址
`TRIPO_HOME`	配置和历史目录，默认为 `~/.tripo`
`TRIPO_NO_UPDATE_CHECK`	设为任意非空值（如 `1`），关闭启动时的自动版本检查
`TRIPO_NPM_REGISTRY`	CLI 版本查询使用的 registry 地址，默认为 `https://registry.npmjs.org`；安装源沿用 npm 配置
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	CLI 网络请求的代理地址与排除列表，也支持小写变量名
`TRIPO_ANALYTICS_ENABLED`	仅设为 `0` 时关闭匿名使用统计；国内区域及自定义 API 地址不发送
`TRIPO_LLM_BASE_URL`	`tripo ai` 可选的 OpenAI 兼容接口
`TRIPO_LLM_API_KEY`	`tripo ai` 可选的 LLM Key
`TRIPO_LLM_MODEL`	`tripo ai` 可选的 LLM 模型