# 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 或自有业务系统 | [快速开始](/zh/docs/quick-start) |

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

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

以下安装方式二选一

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

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

```text
请帮我安装并配置 Tripo CLI，同时解释每一步。先确认本机已安装 Node.js 20 或更高版本，再执行 npm install -g tripo-cli。然后请让我在浏览器中完成 tripo login，不要让我把 API Key 粘贴到聊天中。最后运行 tripo doctor，并告诉我认证、网络和余额检查是否通过。
```

接下来会发生什么：

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

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

<details>
<summary><strong>遇到问题？</strong>AI 卡住或报错了</summary>

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

</details>

### 方式二：我自己安装

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

**第 1 步：安装 Tripo CLI**

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

```bash
npm install -g tripo-cli
```

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

<details>
<summary><strong>遇到问题？</strong>找不到 npm，或提示权限不足</summary>

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

</details>

**第 2 步：登录 Tripo 账号**

```bash
tripo login
```

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

![显示验证码的 Tripo CLI 浏览器设备授权页面](/assets/images/docs/cli/device-authorization-zh.webp)

<details>
<summary><strong>遇到问题？</strong>浏览器没打开，或登录没有完成</summary>

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

</details>

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

```bash
tripo doctor
```

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

<details>
<summary><strong>遇到问题？</strong>某一项检查没通过</summary>

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

</details>

<details>
<summary><strong>备用登录方式与区域说明</strong>（浏览器登录不可用时再看）</summary>

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

</details>

## 生成你的第一个 3D 模型

**第 1 步：用一句话生成**

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

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

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

<details>
<summary><strong>遇到问题？</strong>生成没有开始，或中途失败</summary>

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

</details>

**第 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
```

<details>
<summary><strong>Skill 内置文件一览</strong></summary>

```text
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
```

</details>

## 命令参考

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

<details>
<summary><strong>展开完整命令表与通用参数</strong></summary>

| 命令 | 作用 |
| --- | --- |
| `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`。

</details>

## 现成场景与流水线

这是进阶内容，第一次生成时不需要。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`。

<details>
<summary><strong>展开退出码表</strong></summary>

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

</details>

## 自动化环境变量

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

<details>
<summary><strong>展开环境变量表</strong></summary>

| 变量 | 用途 |
| --- | --- |
| `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 模型 |

</details>