Testo in modello 3D

POST /v3/generation/text-to-model

Genera un modello 3D da un messaggio di testo.

Richiedi parametri

Richiedi intestazioni

Parametro	Digitare	Obbligatorio	Predefinito	Descrizione
Content-Type	stringa	Sì	-	`application/json`
Authorization	stringa	Sì	-	`Bearer {api_key}`

Parametro	Digitare	Obbligatorio	Predefinito	Descrizione
prompt	stringa	Sì	-	Richiesta di testo, fino a 1024 caratteri
model	stringa	No	`tripo-v3.1`	Versione modello AI. Valori supportati: `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`
negative_prompt	stringa	No	-	Prompt negativo, fino a 255 caratteri
model_seed	intero	No	Casuale	Seme casuale per la generazione della geometria
image_seed	intero	No	Casuale	Seme casuale per la fase da testo a immagine
face_limit	intero	No	Adattivo	Numero massimo di poligoni per l’output
texture	booleano	No	`true`	Abilita mappe texture
pbr	booleano	No	`true`	Abilita materiali PBR. Quando abilitato, `texture` è forzato su `true`
texture_seed	intero	No	Casuale	Seme casuale per la generazione di texture
texture_quality	stringa	No	`standard`	Qualità della trama. Valori supportati: `fast` (richiede `texture_version=v3.5-20260815`), `standard`, `detailed`, `extreme`
texture_version	stringa	No	Derivato da model	Fissa il modello di texture indipendentemente dalla geometria. Valori supportati: `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. Se omesso, viene derivato dal `model` della geometria (geometria v2.5 → `v2.5-20250123`, altrimenti `v3.0-20250812`)
delight	booleano	No	`true`	Rimuove l’illuminazione incorporata dall’immagine di riferimento prima della texturizzazione. Considerato solo quando `texture_version=v3.5-20260815`
geometry_quality	stringa	No	`standard`	Qualità della geometria. `standard` (bilanciato), `detailed` (modalità Ultra)
auto_size	booleano	No	`false`	Ridimensiona automaticamente il modello alle dimensioni reali in metri
quad	booleano	No	`false`	Produci una mesh quadrupla. Quando abilitato, il formato di output viene forzato su FBX
smart_low_poly	booleano	No	`false`	Genera un modello low-poly con stile topologico realizzato a mano
generate_parts	booleano	No	`false`	Genera parti segmentate modificabili. Non compatibile con `texture`, `pbr`, `quad` o `smart_low_poly` — vedi nota sotto
compress	stringa	No	-	Tipo di compressione. `geometry` (compressione meshopt)
export_orientation	stringa	No	`+x`	Orientamento all’esportazione. Valori disponibili: `-x`, `-y`, `+y`

Note su generate_parts:

Non compatibile con texture, pbr, quad o smart_low_poly:

texture=true o pbr=true — inclusa l’omissione di texture, che per impostazione predefinita è true — la richiesta viene rifiutata con codice di errore 1004.
quad=true — quad viene ignorato; le parti restituite sono mesh triangolari.
smart_low_poly=true — smart_low_poly ha la precedenza e le parti NON vengono prodotte.

Per generare parti, imposta texture=false e pbr=false, e non inviare quad né smart_low_poly.

Note su export_orientation:

Si applica solo a questa generazione. Se il modello verrà utilizzato in attività di post-elaborazione (texture, rig, retarget, conversione, …), si consiglia di non impostare questo parametro.
Se impostato, la post-elaborazione può compromettere il risultato finale a causa di un orientamento errato del modello, pur riportando status: success — non viene sollevato alcun errore. Usare con cautela.
Se prevedi di post-elaborare il modello, lascia questo parametro non impostato e converti l’orientamento nell’ultimo passaggio tramite /v3/models/convert.

I seguenti parametri sono validi solo quando model >= tripo-v3.0: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

Richiedi esempi

curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/text-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": True,
    "pbr": True,
    "texture_quality": "detailed"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/generation/text-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    prompt: "A cat wearing a spacesuit",
    model: "tripo-v3.1",
    texture: true,
    pbr: true,
    texture_quality: "detailed"
  })
});

const data = await response.json();
console.log(data);

Risposta

Risposta di successo

JSON

{
  "code": 0,
  "data": {
    "task_id": "task_abc123"
  }
}

Campi di risposta

Parametro	Digitare	Descrizione
code	intero	Codice di stato. `0` indica successo
data.task_id	stringa	Identificatore univoco dell’attività utilizzato per interrogare l’avanzamento e i risultati della generazione

Codici di errore

HTTP Codice di stato	Codice errore	Descrizione	Raccomandazione
429	2000	Limite di generazione superato	Ridurre la frequenza delle richieste e riprovare più tardi
400	2002	Parametro di richiesta non supportato	Controllare i nomi dei parametri del corpo della richiesta e gli intervalli di valori
400	2008	L’input viola le norme sui contenuti	Rivedi la richiesta e rimuovi le descrizioni che violano le policy
403	2010	Crediti insufficienti	Aggiungi crediti e riprova
400	2015	Versione del modello deprecata	Aggiorna `model` a una versione attualmente supportata
400	2018	Il modello è troppo complesso per essere rimesh	Abbassa `face_limit` o semplifica la richiesta di input