Tripo CLI: lascia che l’IA trasformi testo e immagini in modelli 3D

Tripo CLI è progettata per gli agenti IA e rende la creazione 3D semplice come chattare. Che tu stia lavorando in uno strumento di coding IA come Codex, Claude Code o Cursor, o usando direttamente la CLI, bastano una descrizione in linguaggio naturale, un’immagine o un modello esistente per generare o trasformare modelli 3D, animazioni e altri asset. La CLI completa automaticamente l’intero flusso: non serve conoscere API, versioni dei modelli o parametri complessi.

Devo usare la CLI o l’API?

Tripo è disponibile in due versioni: prenditi dieci secondi per scegliere quella giusta.

Prodotto	Ideale per	Dove andare
Tripo CLI (questa pagina)	Principianti: accedi rapidamente alle funzionalità di IA 3D tramite i più diffusi strumenti di vibe coding	Continua a leggere
Tripo API	Sviluppatori professionisti: integra le funzionalità di IA 3D in siti web, app o nei tuoi sistemi aziendali	Guida rapida

Non sei sicuro? Prova prima questa pagina: l’installazione è gratuita e i crediti si spendono solo quando generi davvero un modello.

Installazione e accesso (scegli uno dei due percorsi)

Scegli uno dei due percorsi di installazione qui sotto.

Percorso uno: fai installare tutto all’IA (consigliato)

Se usi già Cursor, Claude Code, Codex o un altro assistente IA in grado di eseguire comandi nel terminale, questo è il percorso più semplice. Copia il prompt qui sotto e invialo per intero al tuo assistente:

Configura Tripo CLI per me e spiega ogni passaggio. Verifica che Node.js 20 o successivo sia installato, quindi esegui npm install -g tripo-cli. Se questo è Windows PowerShell e l’esecuzione di script è disabilitata, esegui Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (non come amministratore) e riprova. Prima di accedere, chiedimi quale sito usa il mio account: il sito internazionale developers.tripo3d.ai (ov) o il sito della Cina continentale developers.tripo3d.com (cn). Non dedurlo dalla mia lingua o dal metodo di accesso. Esegui tripo login --region ov o tripo login --region cn in base alla mia risposta. Trasmettimi l’URL di verifica e il codice monouso, e lascia il comando in esecuzione mentre autorizzo nel browser; non chiedermi di incollare una chiave API nella chat. Infine, esegui tripo doctor e dimmi se i controlli di autenticazione, rete e saldo sono superati.

Ecco cosa succede:

L’IA controlla il tuo computer e, se Node.js manca, ti aiuta prima a installarlo;
L’IA esegue il comando di installazione;
Tocca a te: conferma il sito del tuo account, apri l’URL di verifica fornito dall’IA e inserisci o controlla il codice monouso mostrato nel terminale prima di autorizzare (questo passaggio spetta a te; non inviare mai nessuna chiave all’IA);
L’IA esegue tripo doctor; quando tutti i controlli sono superati, la configurazione è completa.

Poi passa direttamente alla sezione successiva, “Crea il tuo primo modello 3D”.

Problemi? L’IA si è bloccata o ha incontrato un errore

Incolla all’IA l’errore del terminale così com’è e lasciala continuare: può risolvere la maggior parte dei problemi;
L’accesso non si è completato: riapri la pagina di accesso e ricontrolla il codice di verifica mostrato nel tuo terminale prima di approvare;
Se nulla funziona, passa al “Percorso due: installazione manuale” qui sotto: sono solo tre comandi.

Percorso due: installazione manuale

Nessun assistente IA? Nessun problema: l’intero processo si riduce a tre comandi.

Passaggio 1: installa Tripo CLI

Questo comando installa il comando tripo sul tuo computer:

Bash

npm install -g tripo-cli

Normalmente l’avanzamento termina senza messaggi di errore in rosso: significa che l’installazione è riuscita.

Hai già installato la CLI? Esegui tripo update --check per cercare una versione più recente, poi tripo update per installarla.

Problemi? npm non trovato, o un errore di permessi

npm non trovato: Node.js non è ancora installato. Installa la versione LTS corrente (20 o successiva) dal sito di Node.js, poi riapri il terminale e riprova;
Errore di permessi su macOS (EACCES): esegui invece sudo npm install -g tripo-cli e inserisci la password del computer quando richiesta;
Windows dice che “l’esecuzione di script è disabilitata”: esegui Set-ExecutionPolicy -Scope CurrentUser RemoteSigned in PowerShell (non servono i privilegi di amministratore), riapri il terminale e riprova. Altri esempi sono più sotto in “Windows / PowerShell”.

Passaggio 2: accedi al tuo account Tripo

Per un account internazionale su developers.tripo3d.ai (fatturazione Stripe), esegui:

Bash

tripo login --region ov

Per un account della Cina continentale su developers.tripo3d.com (Alipay), usa invece tripo login --region cn. In un terminale interattivo, tripo login senza regione chiede prima di scegliere il sito dell’account.

Il browser apre automaticamente la pagina di autorizzazione del sito selezionato (se non hai ancora un account, registrati lì prima). Inserisci o controlla il codice monouso mostrato nel terminale, poi autorizza. Dopo l’autorizzazione, la CLI riceve automaticamente la chiave e conferma che hai effettuato l’accesso.

Pagina di autorizzazione del dispositivo Tripo CLI nel browser con codice di verifica

Problemi? Il browser non si è aperto, o l’accesso non si è completato

L’accesso non si è completato: esegui di nuovo tripo login e approva solo dopo aver ricontrollato il codice mostrato nel tuo terminale;
Il browser non reagisce: copia manualmente nel browser l’URL stampato nel terminale;
L’autorizzazione nel browser è temporaneamente non disponibile: in un terminale interattivo la CLI passa alla pagina della chiave API. In un agente IA o in un’altra sessione non interattiva, usa TRIPO_API_KEY con il TRIPO_REGION corretto, esegui tripo login --key tsk_... o riprova in un terminale interattivo — vedi “Accesso di riserva e regioni” qui sotto.

Passaggio 3: verifica che tutto sia pronto

Bash

tripo doctor

Controlla in sequenza lo stato dell’accesso, la connessione di rete e il saldo dei crediti. Quando tutti e tre i controlli passano, la configurazione è completa.

Problemi? Uno dei controlli non è passato

Controllo di autenticazione non superato: l’accesso non si è completato — esegui tripo login e accedi di nuovo;
Controllo di rete non superato: verifica che il computer possa aprire le pagine web; le reti aziendali o universitarie potrebbero richiedere un proxy;
Controllo del saldo non superato: non hai crediti sufficienti; non è partita alcuna generazione e non ti è stato addebitato nulla. Esegui tripo topup per aprire la pagina di fatturazione.

Accesso di riserva e regioni (solo se l’accesso dal browser non è disponibile)

Se hai già una chiave API, esegui tripo login --key tsk_... oppure imposta TRIPO_API_KEY insieme a TRIPO_REGION (ov o cn) per quell’account;
Una chiave API è una credenziale dell’account: non incollarla mai in chat, codice sorgente, screenshot o log;
tripo login --key tsk_... verifica entrambe le regioni e salva automaticamente quella che accetta la chiave. Impostare direttamente TRIPO_API_KEY non esegue questo rilevamento. Prima dell’autorizzazione nel browser, scegli esplicitamente il sito: ov per l’internazionale e cn per la Cina continentale;
In un agente IA o in un’altra sessione non interattiva senza chiave, --region è obbligatorio. La CLI stampa un URL di verifica e un codice monouso, poi attende che una persona autorizzi. Chiedi quale sito usa l’account prima di iniziare; non dedurlo dalla lingua o dal metodo di accesso.

Windows / PowerShell

I comandi in questa pagina sono mostrati in Bash. Funzionano anche su Windows; PowerShell analizza solo alcuni token in modo diverso da Bash o cURL. In PowerShell usa gli esempi qui sotto invece di copiare i blocchi Bash così come sono.

Consentire l’esecuzione di tripo

npm installa uno shim tripo.ps1 che PowerShell blocca per impostazione predefinita:

PowerShell

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Riapri il terminale ed esegui tripo doctor. Non servono i privilegi di amministratore. Se preferisci non cambiare i criteri, usa il Prompt dei comandi (cmd.exe).

Virgolettare @last e i flag separati da virgole

PowerShell tratta @name come sintassi speciale e , come separatore di elenco:

PowerShell

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

Il Prompt dei comandi non richiede queste virgolette extra.

Variabili d’ambiente

PowerShell

# Solo la finestra corrente
$env:TRIPO_API_KEY = "tsk_..."
$env:TRIPO_REGION = "ov"
$env:TRIPO_PROFILE = "work-ov"

# Persistere per il tuo utente Windows
[System.Environment]::SetEnvironmentVariable("TRIPO_API_KEY", "tsk_...", "User")
[System.Environment]::SetEnvironmentVariable("TRIPO_REGION", "ov", "User")

Configurazione e cronologia si trovano in %USERPROFILE%\.tripo (l’equivalente Windows di ~/.tripo).

Pipeline JSON

PowerShell

# PowerShell 7+ (consigliato)
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 un prompt non in inglese compare distorto, usa Windows Terminal oppure esegui prima chcp 65001.

Crea il tuo primo modello 3D

Passaggio 1: genera a partire da una frase

Le parole tra virgolette sono il tuo prompt: sostituiscile con ciò che vuoi creare:

Bash

tripo make "a cute low poly fox"

Tieni aperto il terminale mentre il comando è in esecuzione. Tripo CLI sceglie il workflow e il modello giusti, attende che l’attività finisca e scarica i file in una cartella tripo-out nella directory corrente. L’intera esecuzione di solito si conclude in pochi minuti e costa una piccola quantità di crediti.

Problemi? La generazione non è partita, o si è interrotta a metà

Crediti insufficienti: il tuo modello non ha iniziato la generazione e non ti è stato addebitato nulla. Esegui tripo topup per aggiungere crediti, poi riprova;
Errore di rete o HTTP 5xx durante l’invio: l’attività potrebbe esistere già sul server. Controlla con tripo balance se ci sono crediti congelati e ispeziona la console prima di inviare di nuovo. Se hai un ID attività, riprendi con tripo task watch <task-id> --download;
L’attesa è scaduta: l’attività potrebbe essere ancora in esecuzione e verrà addebitata se riesce. Riprendi con tripo task watch <task-id> --download; non ripetere make e non usare redo per recuperare da un timeout;
Attività non riuscita: gli eventuali crediti addebitati vengono rimborsati automaticamente — prova con una descrizione diversa.

Passaggio 2: apri l’anteprima

Bash

tripo view @last

@last significa “attività più recente”. Il browser apre un’anteprima 3D interattiva che puoi ruotare trascinando — quando vedi il tuo modello, ce l’hai fatta! In PowerShell scrivi tripo view '@last'.

Dopo il primo successo: che cosa hai adesso

Dove sono i file: una nuova cartella sotto tripo-out contiene il modello 3D scaricato e task.json, che registra come è stata creata l’attività; se il server fornisce un’immagine di anteprima trovi anche preview.png.
Riaprirlo: esegui tripo view @last in qualsiasi momento, oppure tripo view <file> per aprire qualunque file di modello.
Quanto è costato: esegui tripo balance per controllare il saldo dei crediti.
Odi memorizzare i comandi? Esegui semplicemente tripo per aprire un menu interattivo guidato: accesso, generazione, anteprima e ricarica sono tutti lì.
Prossimi passi: genera da immagini (sezione successiva), lascia guidare un assistente IA (“Lascia che gli agenti di programmazione IA padroneggino la CLI”) oppure elabora in blocco (“Workflow pronti e pipeline”).

Genera da un’immagine o da un modello esistente

Dopo che l’esempio testuale funziona, puoi passare file locali. concept.png, front.png e hero.glb qui sotto sono nomi di esempio: sostituiscili con i percorsi dei tuoi file:

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

Riga 1: trasforma un’immagine concept in un modello pronto per la stampa;
Riga 2: genera dalle immagini fronte e retro insieme, per dettagli più accurati;
Riga 3: esegue il texturing e il rigging di un modello esistente;
Riga 4: converte il risultato più recente in FBX.

Lascia che gli agenti di programmazione IA padroneggino la CLI

Se non usi un agente di programmazione IA, salta questa sezione. Il pacchetto npm include un Agent Skill — riferimenti dei comandi, ricette per gli scenari e indicazioni per il recupero dagli errori — così un agente può usare la CLI correttamente. Fai eseguire all’agente questi comandi per visualizzare nel terminale le istruzioni complete o un singolo argomento:

Bash

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

File inclusi nello 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

Riferimento dei comandi

Non serve memorizzare questa tabella: nell’uso quotidiano, ai nuovi utenti bastano tripo (menu interattivo), tripo make (generazione), tripo view (anteprima) e tripo doctor (diagnostica). Espandi il resto solo quando emerge un’esigenza specifica.

Mostra la tabella completa dei comandi e le opzioni comuni

Comando	Funzione
`tripo make <input...>`	Genera, elabora e scarica con un solo comando
`tripo ai [description]`	Pianifica un lavoro, lo conferma e lo esegue
`tripo view [task\|file]`	Apre un’anteprima 3D locale interattiva
`tripo redo [task]`	Ripete una richiesta con un nuovo seed
`tripo login / logout / whoami / use`	Autorizza i profili account denominati e passa da uno all’altro
`tripo topup / balance / usage`	Apre la fatturazione regionale e controlla i crediti
`tripo generate <endpoint>`	Accede esplicitamente a tutti e otto gli endpoint di generazione
`tripo model / anim / mesh <step>`	Esegue perfezionamento, texturing, rigging, conversione, segmentazione e altri passaggi di elaborazione
`tripo mesh decimate [input]`	Riduce il numero di poligoni; v3.0 può eseguire l’unwrap UV nella stessa attività
`tripo mesh uv [input]`	Esegue l’unwrap UV e rimappa le texture, il rigging e l’animazione esistenti
`tripo task get/list/watch`	Interroga, elenca o attende le attività
`tripo history [--limit <n>]`	Mostra la cronologia locale delle attività recenti
`tripo files upload <path>`	Carica un file e ne restituisce il `file_token`
`tripo batch run <manifest.yaml>`	Esegue pipeline in blocco ripristinabili, con concorrenza e nuovi tentativi
`tripo config / doctor`	Gestisce le impostazioni e diagnostica l’ambiente locale
`tripo update [--check]`	Installa la CLI più recente oppure controlla solo la disponibilità di un aggiornamento
`tripo docs [--topic <topic>]`	Visualizza la documentazione inclusa dell’Agent e dei comandi
`tripo mcp`	Esegue la CLI come server MCP
`tripo completion <shell>`	Genera il completamento per Bash, Zsh o Fish (non per PowerShell)

I comandi make, ai e generate, insieme ai sottocomandi di elaborazione di model, anim e mesh, supportano -o/--out, --no-wait, --no-download, --name, --timeout, --notify e l’opzione ripetibile --param key=value. Le opzioni globali di automazione includono --json, --yes, --quiet, --no-open e --profile.

Workflow pronti e pipeline

Questa sezione è avanzata e non serve per la prima generazione. Sette preimpostazioni integrate applicano in una volta parametri e passaggi di elaborazione utili tramite --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 unwrap UV

decimate usa ancora v2.0 per impostazione predefinita. Scegli v3.0 per il modello di retopologia più recente; --smart-uv esegue l’unwrap UV nella stessa attività e supporta solo v3.0 (se ometti --model con questo flag, viene selezionato v3.0).

Bash

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

Il passaggio separato uv rimappa le texture, il rigging e l’animazione esistenti sul nuovo layout UV e restituisce anche un atlante UV. L’input non deve superare 80.000 triangoli equivalenti (un quad conta come due triangoli). Per i modelli più grandi, riduci prima i poligoni, per esempio con tripo make hero.glb --then decimate:20000,uv. In PowerShell, racchiudi la catena tra virgolette: 'decimate:20000,uv'.

I riferimenti alle attività come @last, @2 e @name funzionano ovunque sia accettato un ID attività.

Più account e regioni

Se usi un solo account Tripo, salta questa sezione. Le credenziali vengono archiviate in profili denominati, quindi l’accesso a un secondo account non sovrascrive il primo:

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

Ogni profilo conserva la propria chiave e la propria regione. La variabile d’ambiente TRIPO_PROFILE seleziona un profilo per l’ambiente corrente. TRIPO_API_KEY sostituisce la chiave salvata, ma non rileva automaticamente la relativa regione; quando fornisci una chiave tramite l’ambiente, imposta TRIPO_REGION in modo che corrisponda all’account.

Usa la regione che corrisponde a ciascun account. tripo topup apre la pagina di fatturazione regionale del profilo attivo: /billing sul sito internazionale oppure /billing/recharge sul sito della Cina continentale.

Note per gli agenti di programmazione IA

Gli utenti umani possono saltare questa sezione. Queste regole aiutano un agente di programmazione IA ad attendere correttamente le attività e a leggere l’output elaborabile dalle macchine.

tripo make e tripo task watch sono comandi bloccanti. Attendi il completamento del processo invece di implementare un altro ciclo di polling.
Con --json, la maggior parte dei comandi eseguiti una sola volta scrive una riga JSON finale in stdout. tripo task watch --json, invece, trasmette eventi di avanzamento NDJSON seguiti dal risultato finale.
Se preview.png esiste, controllalo prima di decidere se proseguire una pipeline o eseguire tripo redo.
Non inventare parametri e non forzare versioni di modelli precedenti. Usa tripo docs --topic ... per conoscere le opzioni supportate.
Una richiesta low-poly o un budget massimo di 20.000 facce seleziona tripo-p1; gli altri lavori usano tripo-v3.1 per impostazione predefinita.
tripo-p2 è un modello Preview e deve essere selezionato esplicitamente con --model tripo-p2. Per un output low-poly in quad, aggiungi -p quad=true; l’output in quad usa FBX e P1 non supporta i quad. Usa gli alias dei modelli della CLI; la CLI li converte nei valori di modello datati attesi dall’API.
Ispeziona un piano senza caricare file, creare attività o spendere crediti con tripo make "a low-poly robot" --model tripo-p2 --dry-run.
La creazione delle attività viene ritentata automaticamente solo per HTTP 429. Un errore di rete, un timeout o HTTP 5xx può rendere incerto l’esito dell’invio; controlla l’account prima di inviare di nuovo.

Mostra la tabella dei codici di uscita

Codice di uscita	Significato
`0`	Operazione riuscita
`1`	Errore imprevisto o interno
`2`	Utilizzo o parametri non validi
`3`	Errore di autenticazione
`4`	Crediti insufficienti
`5`	Rifiuto in base alle norme sui contenuti
`6`	Attività non riuscita (crediti rimborsati) oppure attesa scaduta (l’attività potrebbe essere ancora in esecuzione; riprendi il monitoraggio)
`7`	Errore di rete
`8`	Risorsa non trovata
`9`	Limite di frequenza raggiunto; riprova con backoff

Variabili d’ambiente per l’automazione

Le variabili d’ambiente non servono per l’uso interattivo normale: esistono per CI, script e workflow avanzati con agenti. Ricorda: non eseguire mai il commit di una chiave API in un repository, non incollarla nella documentazione e non includerla in screenshot o log.

Le analisi di utilizzo anonime sono abilitate per impostazione predefinita per l’API ufficiale internazionale e usano un ID di installazione casuale. Registrano gli esiti dei comandi e i metadati delle attività, tra cui modello/tipo, crediti/durata, categoria di errore, formato di output/numero di file e attribuzione dell’agente; prompt, percorsi dei file, asset di input, chiavi API e URL di download sono esclusi. Gli endpoint della Cina continentale e le API personalizzate non inviano questi eventi. Imposta TRIPO_ANALYTICS_ENABLED=0 per disattivarle.

Mostra la tabella delle variabili d’ambiente

Variabile	Scopo
`TRIPO_API_KEY`	Sostituisce la chiave salvata senza rilevarne la regione; usala negli script con il `TRIPO_REGION` corretto
`TRIPO_PROFILE`	Profilo account denominato, equivalente a `--profile`
`TRIPO_REGION`	Override `ov` o `cn` per le richieste API; non sostituisce `login --region` per l’autorizzazione del browser non interattiva
`TRIPO_API_BASE_URL`	Override dell’endpoint API
`TRIPO_PLATFORM_BASE_URL`	Override dell’endpoint della piattaforma
`TRIPO_HOME`	Directory di configurazione e cronologia; il valore predefinito è `~/.tripo`
`TRIPO_NO_UPDATE_CHECK`	Qualsiasi valore non vuoto (ad esempio `1`) disabilita i controlli automatici della versione all’avvio
`TRIPO_NPM_REGISTRY`	URL del registro per le richieste della versione CLI; il valore predefinito è `https://registry.npmjs.org`. L’installazione usa la configurazione del registro npm
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	URL dei proxy e lista di esclusione per le richieste di rete della CLI; funzionano anche i nomi in minuscolo
`TRIPO_ANALYTICS_ENABLED`	Imposta esattamente `0` per disabilitare le analisi di utilizzo anonime; la Cina continentale e le API personalizzate non ne inviano
`TRIPO_LLM_BASE_URL`	Endpoint facoltativo compatibile con OpenAI per `tripo ai`
`TRIPO_LLM_API_KEY`	Chiave LLM facoltativa per `tripo ai`
`TRIPO_LLM_MODEL`	Modello LLM facoltativo per `tripo ai`