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。然后请让我在浏览器中完成 tripo login，不要让我把 API Key 粘贴到聊天中。最后运行 tripo doctor，并告诉我认证、网络和余额检查是否通过。

接下来会发生什么：

AI 检查电脑环境，缺 Node.js 时会先带你装好；
AI 运行安装命令；
轮到你：浏览器会打开 Tripo 登录页，登录并确认终端里显示的验证码（这一步必须本人完成，不要把任何密钥发给 AI）；
AI 运行 tripo doctor 检查，全部通过就安装完成了。

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

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

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

方式二：我自己安装

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

第 1 步：安装 Tripo CLI

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

Bash

npm install -g tripo-cli

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

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

提示找不到 npm：说明 Node.js 还没装好。前往 Node.js 官网安装当前 LTS 版本（20 或更高），装完后重新打开终端再运行一次；
macOS 提示权限不足（EACCES）：改用 sudo npm install -g tripo-cli，按提示输入电脑密码；
Windows 提示“禁止运行脚本”：用管理员身份重新打开 PowerShell 再运行一次。

第 2 步：登录 Tripo 账号

Bash

tripo login

浏览器会自动打开授权页面（还没有账号就先在页面上注册一个）。页面会显示一个验证码，确认它和你终端里显示的验证码一致后再点确认。登录成功后，终端会提示已登录。

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

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

登录没有完成：重新运行 tripo login，在打开的页面里核对终端显示的验证码后确认；
浏览器一直没有反应：把终端里显示的网址手动复制到浏览器打开；
浏览器授权暂时不可用：CLI 会改为打开 API Key 页面，见本节末尾的“备用登录方式与区域说明”。

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

Bash

tripo doctor

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

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

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

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

已有 API Key 时，可以运行 tripo login --key tsk_... 直接登录，或设置环境变量 TRIPO_API_KEY；
API Key 相当于账号凭证，不要粘贴到聊天、代码、截图或日志中；
同一套安装同时支持海外与中国大陆账号：CLI 会用 Key 探测两个区域，并自动保存可用区域，无需手动选择。

生成你的第一个 3D 模型

第 1 步：用一句话生成

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

Bash

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

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

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

提示积分不足：本次模型还没有开始生成，不会扣费。运行 tripo topup 充值后重试；
网络错误：确认电脑联网正常后，重新运行同一条命令即可；
任务失败：已扣的积分会自动退回，换一个描述再试一次。

第 2 步：打开预览

Bash

tripo view @last

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

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

文件在哪：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

不使用 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 task get/list/watch`	查询、列出或等待任务
`tripo history [--limit <n>]`	查看最近的本地任务历史
`tripo files upload <path>`	上传文件并返回 `file_token`
`tripo batch run <manifest.yaml>`	以并发、重试和断点续跑执行批量流水线
`tripo config / doctor`	管理设置并诊断本地环境
`tripo docs [--topic <topic>]`	输出内置 Agent 与命令文档
`tripo mcp`	以 MCP Server 方式运行 CLI
`tripo completion <shell>`	为 Bash、Zsh 或 Fish 生成自动补全

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

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

多账号与区域

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

Bash

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

每个配置分别保存自己的 Key 和区域。环境变量 TRIPO_PROFILE 可为当前环境选择配置；TRIPO_API_KEY 会绕过所有配置，优先级最高。

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。

展开退出码表

退出码	含义
`0`	成功
`1`	意外或内部错误
`2`	用法或参数错误
`3`	认证错误
`4`	积分不足
`5`	内容安全策略拒绝
`6`	任务失败；积分自动退回
`7`	网络错误
`8`	资源不存在
`9`	触发限流；应退避后重试

自动化环境变量

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

展开环境变量表

变量	用途
`TRIPO_API_KEY`	API Key；优先级最高，适合 CI 或 Agent
`TRIPO_PROFILE`	命名账号配置，等价于 `--profile`
`TRIPO_REGION`	可选的 `ov` 或 `cn` 覆盖；通常由 CLI 自动识别
`TRIPO_API_BASE_URL`	覆盖 API 地址
`TRIPO_PLATFORM_BASE_URL`	覆盖平台地址
`TRIPO_HOME`	配置和历史目录，默认为 `~/.tripo`
`TRIPO_LLM_BASE_URL`	`tripo ai` 可选的 OpenAI 兼容接口
`TRIPO_LLM_API_KEY`	`tripo ai` 可选的 LLM Key
`TRIPO_LLM_MODEL`	`tripo ai` 可选的 LLM 模型