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

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:

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. Se isto for o Windows PowerShell e a execução de scripts estiver desabilitada, execute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (não como administrador) e tente novamente. Antes de fazer login, pergunte qual site a minha conta usa: o site internacional developers.tripo3d.ai (ov) ou o site da China continental developers.tripo3d.com (cn). Não adivinhe pelo meu idioma ou pelo método de login. Execute tripo login --region ov ou tripo login --region cn de acordo com a minha resposta. Transmita a URL de verificação e o código de uso único para mim e mantenha o comando em execução enquanto eu autorizo 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:

A IA verifica o seu computador e, se o Node.js estiver faltando, ajuda você a instalá-lo primeiro;
A IA executa o comando de instalação;
Sua vez: confirme o site da sua conta, abra a URL de verificação fornecida pela IA e insira ou confira o código de uso único exibido no terminal antes de autorizar (esta etapa deve ser feita por você; nunca envie nenhuma chave à IA);
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”.

Problemas? A IA travou ou encontrou um erro

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.

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.

Já instalou? Execute tripo update --check para verificar se há uma versão mais recente e depois tripo update para instalá-la.

Problemas? npm não encontrado ou erro de permissão

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, 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”: execute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned no PowerShell (não é preciso ser administrador), reabra o terminal e tente novamente. Há mais exemplos abaixo em “Windows / PowerShell”.

Passo 2: faça login na sua conta Tripo

Para uma conta internacional em developers.tripo3d.ai (faturamento Stripe), execute:

Bash

tripo login --region ov

Para uma conta da China continental em developers.tripo3d.com (Alipay), use tripo login --region cn em vez disso. Em um terminal interativo, tripo login sem região pede primeiro que você escolha o site da conta.

Seu navegador abre automaticamente a página de autorização do site selecionado (registre-se lá primeiro se ainda não tiver uma conta). Insira ou confira o código de uso único exibido no seu terminal e então autorize. Depois da autorização, a CLI recebe a chave automaticamente e confirma que você fez login.

Página de autorização de dispositivo da Tripo CLI no navegador com código de verificação

Problemas? O navegador não abriu ou o login não foi concluído

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: em um terminal interativo, a CLI volta para a página da API key. Em um agente de IA ou outra sessão não interativa, use TRIPO_API_KEY com o TRIPO_REGION correto, execute tripo login --key tsk_... ou tente novamente em um terminal interativo — veja “Login alternativo e regiões” abaixo.

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.

Problemas? Uma das verificações falhou

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.

Login alternativo e regiões (apenas se o login pelo navegador estiver indisponível)

Se você já tem uma API key, execute tripo login --key tsk_... ou defina TRIPO_API_KEY junto com TRIPO_REGION (ov ou cn) para essa conta;
Uma API key é uma credencial da conta: nunca a cole em chats, código-fonte, capturas de tela ou logs;
tripo login --key tsk_... testa as duas regiões e salva automaticamente a região que aceitar a chave. Definir TRIPO_API_KEY diretamente não realiza essa detecção. Antes da autorização no navegador, escolha explicitamente o site: ov para internacional e cn para a China continental;
Em um agente de IA ou outra sessão não interativa sem chave, --region é obrigatório. A CLI imprime uma URL de verificação e um código de uso único e depois aguarda a autorização de uma pessoa. Pergunte qual site a conta usa antes de começar; não adivinhe pelo idioma nem pelo método de login.

Windows / PowerShell

Os comandos nesta página estão escritos para Bash. Eles também funcionam no Windows; o PowerShell apenas interpreta alguns tokens de forma diferente do Bash ou do cURL. No PowerShell, use os exemplos abaixo em vez de copiar os blocos Bash como estão.

Permitir a execução do tripo

O npm instala um shim tripo.ps1 que o PowerShell bloqueia por padrão:

PowerShell

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Reabra o terminal e execute tripo doctor. Direitos de administrador não são necessários. Se preferir não alterar a política, use o Prompt de Comando (cmd.exe).

Coloque aspas em @last e nas flags separadas por vírgula

O PowerShell trata @name como sintaxe especial e , como separador de lista:

PowerShell

tripo make "a cute low poly fox"
tripo view '@last'
tripo make hero.glb --then 'texture,rig'
tripo make '@last' --then 'convert:fbx'

O Prompt de Comando não precisa dessas aspas extras.

Variáveis de ambiente

PowerShell

# Somente a janela atual
$env:TRIPO_API_KEY = "tsk_..."
$env:TRIPO_REGION = "ov"
$env:TRIPO_PROFILE = "work-ov"

# Persistir para o seu usuário do Windows
[System.Environment]::SetEnvironmentVariable("TRIPO_API_KEY", "tsk_...", "User")
[System.Environment]::SetEnvironmentVariable("TRIPO_REGION", "ov", "User")

Configuração e histórico ficam em %USERPROFILE%\.tripo (o equivalente no Windows de ~/.tripo).

Pipelines JSON

PowerShell

# PowerShell 7+ (recomendado)
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

Se um prompt que não esteja em inglês aparecer corrompido, use o Windows Terminal ou execute chcp 65001 primeiro.

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.

Problemas? A geração não começou ou falhou no meio

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 ou HTTP 5xx durante o envio: a tarefa pode já existir no servidor. Verifique com tripo balance se há créditos congelados e inspecione o console antes de enviar novamente. Se você tiver um ID de tarefa, retome com tripo task watch <task-id> --download;
A espera expirou: a tarefa ainda pode estar em execução e será cobrada se for concluída. Retome com tripo task watch <task-id> --download; não repita make nem use redo para se recuperar de um timeout;
Tarefa falhou: os créditos cobrados são reembolsados automaticamente — tente uma descrição diferente.

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! No PowerShell, escreva tripo view '@last'.

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

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

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.

Mostrar a tabela completa de comandos e as opções comuns

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 mesh decimate [input]`	Reduz a contagem de polígonos; v3.0 pode desdobrar UVs na mesma tarefa
`tripo mesh uv [input]`	Desdobra UVs e remapeia texturas, rigging e animação existentes
`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 update [--check]`	Instala a CLI mais recente ou apenas verifica se há uma atualização
`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 (não para PowerShell)

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.

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

Retopologia e desdobramento de UV

decimate ainda usa v2.0 por padrão. Escolha v3.0 para o modelo de retopologia mais recente; --smart-uv desdobra UVs na mesma tarefa e só oferece suporte a v3.0 (omitir --model com essa opção seleciona v3.0).

Bash

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

A etapa separada uv remapeia texturas, rigging e animação existentes para o novo layout UV e também retorna um atlas UV. A entrada não pode exceder 80.000 triângulos equivalentes (um quad conta como dois triângulos). Para modelos maiores, reduza os polígonos primeiro, por exemplo com tripo make hero.glb --then decimate:20000,uv. No PowerShell, coloque a cadeia entre aspas: 'decimate:20000,uv'.

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 --region ov --profile personal-ov
tripo login --region cn --profile work-cn
tripo use personal-ov
tripo whoami
tripo make "a fox" --profile personal-ov
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. TRIPO_API_KEY substitui a chave salva, mas não detecta automaticamente sua região; ao fornecer uma chave pelo ambiente, defina TRIPO_REGION de acordo com a conta.

Use a região correspondente a cada conta. tripo topup abre a página de faturamento regional do perfil ativo: /billing no site internacional ou /billing/recharge no site da China continental.

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.
tripo-p2 é um modelo Preview e deve ser selecionado explicitamente com --model tripo-p2. Para saída low-poly em quads, adicione -p quad=true; a saída em quads usa FBX, e P1 não oferece suporte a quads. Use os aliases de modelo da CLI; a CLI os converte nos valores de modelo datados esperados pela API.
Inspecione um plano sem fazer upload, criar tarefas ou gastar créditos com tripo make "a low-poly robot" --model tripo-p2 --dry-run.
A criação de tarefas só é repetida automaticamente para HTTP 429. Um erro de rede, timeout ou HTTP 5xx pode deixar o resultado do envio incerto; verifique a conta antes de enviar novamente.

Mostrar a tabela de códigos de saída

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 (créditos reembolsados) ou a espera expirou (a tarefa pode ainda estar em execução; retome o acompanhamento)
`7`	Erro de rede
`8`	Recurso não encontrado
`9`	Limite de requisições atingido; tente novamente com espera progressiva

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.

Análises anônimas de uso são habilitadas por padrão para a API oficial internacional e usam um ID de instalação aleatório. Elas registram resultados de comandos e metadados de tarefas, incluindo modelo/tipo, créditos/duração, categoria de erro, formato de saída/contagem de arquivos e atribuição do agente; prompts, caminhos de arquivos, assets de entrada, API keys e URLs de download são excluídos. Os endpoints da China continental e de API personalizada não enviam esses eventos. Defina TRIPO_ANALYTICS_ENABLED=0 para desativá-las.

Mostrar a tabela de variáveis de ambiente

Variável	Finalidade
`TRIPO_API_KEY`	Substitui a chave salva sem detectar sua região; use-a em scripts com o `TRIPO_REGION` correto
`TRIPO_PROFILE`	Perfil de conta nomeado, equivalente a `--profile`
`TRIPO_REGION`	Substituição `ov` ou `cn` para solicitações de API; não substitui `login --region` para a autorização do navegador não interativa
`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_NO_UPDATE_CHECK`	Qualquer valor não vazio (por exemplo, `1`) desativa as verificações automáticas de versão ao iniciar
`TRIPO_NPM_REGISTRY`	URL do registro para consultas de versão da CLI; o padrão é `https://registry.npmjs.org`. A instalação usa a configuração de registro do npm
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	URLs de proxy e lista de bypass para solicitações de rede da CLI; nomes em minúsculas também funcionam
`TRIPO_ANALYTICS_ENABLED`	Defina exatamente `0` para desativar análises anônimas de uso; a China continental e os endpoints de API personalizada não enviam nenhuma
`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`