# Tripo CLI: deixe a IA transformar texto e imagens em modelos 3D

A Tripo CLI foi criada para agentes de IA e torna a criação 3D tão simples quanto conversar. Seja em uma ferramenta de programação com IA como Codex, Claude Code ou Cursor, seja usando a CLI diretamente, basta uma descrição em linguagem natural, uma imagem ou um modelo existente para gerar ou transformar modelos 3D, animações e outros recursos. A CLI conclui todo o fluxo automaticamente — sem precisar entender APIs, versões de modelos ou parâmetros complexos.

## Devo usar a CLI ou a API?

A Tripo existe em dois formatos — reserve dez segundos para escolher o mais adequado:

| Produto | Ideal para | Onde ir |
| --- | --- | --- |
| **Tripo CLI (esta página)** | Iniciantes: acesse rapidamente os recursos de IA 3D por meio das ferramentas populares de vibe coding | Continue lendo |
| **Tripo API** | Desenvolvedores profissionais: integre os recursos de IA 3D a sites, aplicativos ou aos seus próprios sistemas de negócio | [Início rápido](/pt/docs/quick-start) |

Ficou na dúvida? Experimente esta página primeiro: instalar é grátis, e os créditos só são gastos quando você realmente gera um modelo.

## Instale e faça login (escolha um dos dois caminhos)

Escolha um dos dois caminhos de instalação abaixo.

### Caminho um: deixar a IA instalar para mim (recomendado)

Se você já usa Cursor, Claude Code, Codex ou outro assistente de IA capaz de executar comandos no terminal, este é o caminho mais fácil. Copie o prompt abaixo e envie-o por inteiro ao seu assistente:

```text
Configure a Tripo CLI para mim e explique cada etapa. Verifique se o Node.js 20 ou posterior está instalado e execute npm install -g tripo-cli. Depois, peça para eu concluir tripo login no navegador; não peça para eu colar uma API key no chat. Por fim, execute tripo doctor e diga se as verificações de autenticação, rede e saldo foram aprovadas.
```

O que acontece em seguida:

1. A IA verifica o seu computador e, se o Node.js estiver faltando, ajuda você a instalá-lo primeiro;
2. A IA executa o comando de instalação;
3. Sua vez: uma janela do navegador abre a página de login da Tripo — faça login e aprove o código de verificação exibido no seu terminal (esta etapa deve ser feita por você; nunca envie nenhuma chave à IA);
4. A IA executa `tripo doctor`; quando todas as verificações passarem, a configuração está concluída.

Depois, vá direto para a próxima seção, “Crie seu primeiro modelo 3D”.

<details>
<summary><strong>Problemas?</strong> A IA travou ou encontrou um erro</summary>

- Cole a mensagem de erro do terminal de volta para a IA, exatamente como apareceu, e deixe-a continuar; ela consegue resolver a maioria dos problemas;
- O login não foi concluído: reabra a página de login e confira com atenção o código de verificação exibido no seu terminal antes de aprovar;
- Se nada funcionar, recorra ao “Caminho dois: instalar por conta própria” abaixo — são apenas três comandos.

</details>

### Caminho dois: instalar por conta própria

Não tem um assistente de IA? Sem problema — o processo inteiro se resume a três comandos.

**Passo 1: instale a Tripo CLI**

Este comando instala o comando `tripo` no seu computador:

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

Normalmente o progresso termina sem nenhum texto de erro em vermelho, o que significa que a instalação foi bem-sucedida.

<details>
<summary><strong>Problemas?</strong> npm não encontrado ou erro de permissão</summary>

- `npm` não encontrado: o Node.js ainda não está instalado. Instale a versão LTS atual (20 ou posterior) pelo [site do Node.js](https://nodejs.org/), depois reabra o terminal e tente novamente;
- Erro de permissão no macOS (EACCES): execute `sudo npm install -g tripo-cli` e digite a senha do seu computador quando solicitada;
- O Windows diz que “a execução de scripts está desabilitada”: reabra o PowerShell como administrador e tente novamente.

</details>

**Passo 2: faça login na sua conta Tripo**

```bash
tripo login
```

Seu navegador abre uma página de autorização automaticamente (registre-se lá primeiro se ainda não tiver uma conta). A página mostra um código de verificação — **aprove somente depois de confirmar que ele corresponde ao código exibido no seu terminal.** Depois do login, o terminal confirma que você está conectado.

![Página de autorização de dispositivo da Tripo CLI no navegador com código de verificação](/assets/images/docs/cli/device-authorization-en.webp)

<details>
<summary><strong>Problemas?</strong> O navegador não abriu ou o login não foi concluído</summary>

- O login não foi concluído: execute `tripo login` de novo e aprove somente depois de conferir o código exibido no seu terminal;
- O navegador não reage: copie manualmente para o navegador a URL impressa no terminal;
- A autorização pelo navegador está temporariamente indisponível: a CLI abre a página da API key no lugar — veja “Login alternativo e regiões” no fim desta seção.

</details>

**Passo 3: verifique se está tudo pronto**

```bash
tripo doctor
```

Ele verifica, na sequência, o status do login, o acesso à rede e o saldo de créditos. Quando os três passarem, a configuração está concluída.

<details>
<summary><strong>Problemas?</strong> Uma das verificações falhou</summary>

- Autenticação falhou: o login não foi concluído — execute `tripo login` e faça login novamente;
- Rede falhou: confirme que o seu computador consegue abrir páginas web; redes corporativas ou universitárias podem exigir um proxy;
- Saldo falhou: você não tem créditos suficientes; nada começou a ser gerado e nada foi cobrado. Execute `tripo topup` para abrir a página de faturamento.

</details>

<details>
<summary><strong>Login alternativo e regiões</strong> (apenas se o login pelo navegador estiver indisponível)</summary>

- Se você já tem uma API key, execute `tripo login --key tsk_...` ou defina a variável de ambiente `TRIPO_API_KEY`;
- Uma API key é uma credencial da conta: nunca a cole em chats, código-fonte, capturas de tela ou logs;
- A mesma instalação funciona tanto com contas internacionais quanto da China continental: a CLI testa as duas regiões com a sua chave e salva automaticamente a região que a aceitar.

</details>

## Crie seu primeiro modelo 3D

**Passo 1: gere a partir de uma frase**

As palavras entre aspas são o seu prompt — substitua-as pelo que você quiser criar:

```bash
tripo make "a cute low poly fox"
```

Mantenha o terminal aberto enquanto o comando é executado. A Tripo CLI escolhe o fluxo e o modelo adequados, aguarda a tarefa terminar e baixa os arquivos em uma pasta `tripo-out` no diretório atual. A execução completa normalmente termina em poucos minutos e custa uma pequena quantidade de créditos.

<details>
<summary><strong>Problemas?</strong> A geração não começou ou falhou no meio</summary>

- Créditos insuficientes: seu modelo não começou a ser gerado e nada foi cobrado. Execute `tripo topup` para adicionar créditos e tente de novo;
- Erro de rede: confirme que o seu computador está conectado à internet e execute o mesmo comando novamente;
- Tarefa falhou: os créditos cobrados são reembolsados automaticamente — tente uma descrição diferente.

</details>

**Passo 2: abra a prévia**

```bash
tripo view @last
```

`@last` significa “tarefa mais recente”. Seu navegador abre uma prévia 3D interativa que você pode girar arrastando — quando vir o seu modelo, você conseguiu!

**Depois do primeiro sucesso: o que você tem agora**

- **Onde estão os arquivos**: uma nova pasta dentro de `tripo-out` contém o modelo 3D baixado e o `task.json`, que registra como a tarefa foi criada; se o servidor fornecer uma imagem de prévia, você também recebe um `preview.png`.
- **Abrir de novo**: execute `tripo view @last` a qualquer momento, ou `tripo view <file>` para abrir qualquer arquivo de modelo.
- **Quanto custou**: execute `tripo balance` para consultar seu saldo de créditos.
- **Odeia memorizar comandos?** Basta executar `tripo` para abrir um menu interativo guiado — login, geração, prévia e recarga estão todos lá.
- **Próximos passos**: gere a partir de imagens (próxima seção), deixe um assistente de IA no comando (“Deixe agentes de programação com IA dominarem a CLI”) ou processe em lote (“Fluxos prontos e pipelines”).

## Gere a partir de uma imagem ou de um modelo existente

Quando o exemplo com texto funcionar, você pode passar arquivos locais. Os nomes `concept.png`, `front.png` e `hero.glb` abaixo são exemplos — substitua-os pelos caminhos dos seus próprios arquivos:

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

- Linha 1: transforma uma imagem de conceito em um modelo pronto para impressão;
- Linha 2: gera a partir das imagens de frente e de costas juntas, para detalhes mais precisos;
- Linha 3: texturiza e faz o rigging de um modelo existente;
- Linha 4: converte o resultado mais recente para FBX.

## Deixe agentes de programação com IA dominarem a CLI

Pule esta seção se você não usa um agente de programação com IA. O pacote npm inclui uma Agent Skill — referências de comandos, receitas de cenários e orientações de recuperação de erros — para que um agente use a CLI corretamente. Peça ao agente para executar estes comandos e exibir no terminal as instruções completas ou um tópico específico:

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

<details>
<summary><strong>Arquivos incluídos na 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>

## Referência de comandos

Não é preciso memorizar esta tabela: no dia a dia, quem está começando só precisa de `tripo` (menu interativo), `tripo make` (gerar), `tripo view` (prévia) e `tripo doctor` (diagnóstico). Expanda o restante apenas quando surgir uma necessidade específica.

<details>
<summary><strong>Mostrar a tabela completa de comandos e as opções comuns</strong></summary>

| Comando | O que faz |
| --- | --- |
| `tripo make <input...>` | Gera, processa e baixa com um único comando |
| `tripo ai [description]` | Planeja uma tarefa, solicita confirmação e a executa |
| `tripo view [task\|file]` | Abre uma prévia 3D local e interativa |
| `tripo redo [task]` | Repete uma solicitação com uma nova seed |
| `tripo login / logout / whoami / use` | Autoriza e alterna entre perfis de conta nomeados |
| `tripo topup / balance / usage` | Abre o faturamento regional e consulta os créditos |
| `tripo generate <endpoint>` | Acessa explicitamente todos os oito endpoints de geração |
| `tripo model / anim / mesh <step>` | Executa refinamento, texturização, rigging, conversão, segmentação e outras etapas de processamento |
| `tripo task get/list/watch` | Consulta, lista ou aguarda tarefas |
| `tripo history [--limit <n>]` | Mostra o histórico local de tarefas recentes |
| `tripo files upload <path>` | Faz upload de um arquivo e retorna seu `file_token` |
| `tripo batch run <manifest.yaml>` | Executa pipelines em lote retomáveis, com concorrência e novas tentativas |
| `tripo config / doctor` | Gerencia as configurações e diagnostica o ambiente local |
| `tripo docs [--topic <topic>]` | Exibe a documentação incluída para agentes e comandos |
| `tripo mcp` | Executa a CLI como um servidor MCP |
| `tripo completion <shell>` | Gera o autocompletar para Bash, Zsh ou Fish |

Os comandos `make`, `ai` e `generate`, junto com os subcomandos de processamento de `model`, `anim` e `mesh`, oferecem suporte a `-o/--out`, `--no-wait`, `--no-download`, `--name`, `--timeout`, `--notify` e à opção repetível `--param key=value`. As opções globais de automação incluem `--json`, `--yes`, `--quiet`, `--no-open` e `--profile`.

</details>

## Fluxos prontos e pipelines

Esta é uma seção avançada; sua primeira geração não precisa dela. Sete presets integrados aplicam de uma só vez parâmetros e etapas de processamento úteis via `--for <preset>`:

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

```bash
# Mobile game asset: low-poly generation, texture, then FBX
tripo make "sci-fi crate" --for game-mobile

# Print asset: watertight output, STL, and a flat bottom
tripo make "chess knight" --for print

# Explicit processing chain
tripo make cat.png --then texture,rig,convert:fbx

# The same chain as NDJSON pipes
tripo make cat.png --json | tripo model texture --json | tripo anim rig --json

# Resumable batch processing
tripo batch run assets.yaml --concurrency 2
```

Referências de tarefas como `@last`, `@2` e `@name` funcionam em qualquer lugar que aceite um ID de tarefa.

## Várias contas e regiões

Se você usa apenas uma conta Tripo, pule esta seção. As credenciais são armazenadas em perfis nomeados, portanto fazer login em uma segunda conta não sobrescreve a primeira:

```bash
tripo login
tripo login --profile work-cn
tripo use
tripo whoami
tripo make "a fox" --profile work-cn
tripo logout
```

Cada perfil mantém sua própria chave e região. A variável de ambiente `TRIPO_PROFILE` seleciona um perfil para o ambiente atual, enquanto `TRIPO_API_KEY` ignora todos os perfis e tem a prioridade mais alta.

## Notas para agentes de programação com IA

Usuários humanos podem pular esta seção. Estas regras ajudam um agente de programação com IA a aguardar tarefas corretamente e a ler saídas legíveis por máquina.

- `tripo make` e `tripo task watch` são comandos bloqueantes. Aguarde o processo terminar em vez de implementar outro loop de consulta.
- Com `--json`, a maioria dos comandos de execução única grava uma linha JSON final em stdout. Já `tripo task watch --json` transmite eventos de progresso NDJSON seguidos do resultado final.
- Se `preview.png` existir, inspecione-o antes de decidir se deve continuar um pipeline ou executar `tripo redo`.
- Não invente parâmetros nem force versões antigas dos modelos. Use `tripo docs --topic ...` para consultar as opções compatíveis.
- Uma solicitação low-poly ou um limite de 20.000 faces ou menos seleciona `tripo-p1`; outros trabalhos usam `tripo-v3.1` por padrão.

<details>
<summary><strong>Mostrar a tabela de códigos de saída</strong></summary>

| Código de saída | Significado |
| --- | --- |
| `0` | Sucesso |
| `1` | Erro inesperado ou interno |
| `2` | Uso ou parâmetros inválidos |
| `3` | Erro de autenticação |
| `4` | Créditos insuficientes |
| `5` | Rejeição pela política de conteúdo |
| `6` | A tarefa falhou; os créditos são reembolsados automaticamente |
| `7` | Erro de rede |
| `8` | Recurso não encontrado |
| `9` | Limite de requisições atingido; tente novamente com espera progressiva |

</details>

## Variáveis de ambiente para automação

Você não precisa de variáveis de ambiente no uso interativo normal; elas existem para CI, scripts e fluxos avançados com agentes. Lembre-se: nunca faça commit de uma API key em um repositório, não a cole na documentação nem a inclua em capturas de tela ou logs.

<details>
<summary><strong>Mostrar a tabela de variáveis de ambiente</strong></summary>

| Variável | Finalidade |
| --- | --- |
| `TRIPO_API_KEY` | API key; tem a prioridade mais alta e é adequada para CI ou agentes |
| `TRIPO_PROFILE` | Perfil de conta nomeado, equivalente a `--profile` |
| `TRIPO_REGION` | Substituição opcional por `ov` ou `cn`; normalmente detectada automaticamente |
| `TRIPO_API_BASE_URL` | Substituição do endpoint da API |
| `TRIPO_PLATFORM_BASE_URL` | Substituição do endpoint da plataforma |
| `TRIPO_HOME` | Diretório de configuração e histórico; o padrão é `~/.tripo` |
| `TRIPO_LLM_BASE_URL` | Endpoint opcional compatível com OpenAI para `tripo ai` |
| `TRIPO_LLM_API_KEY` | Chave LLM opcional para `tripo ai` |
| `TRIPO_LLM_MODEL` | Modelo LLM opcional para `tripo ai` |

</details>