Immagine nel modello 3D

POST /v3/generation/image-to-model

Genera un modello 3D da un’immagine.

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
input	stringa	Sì	-	Fonte dell’immagine. Accetta un token file che inizia con `file_`, uno URL che inizia con `http(s)://` o un’attività ID che inizia con `task_`
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`
enable_image_autofix	booleano	No	`false`	Usato per il completamento AI e il miglioramento del risultato 3D. Migliora automaticamente le immagini di input di bassa qualità
texture_alignment	stringa	No	`original_image`	Priorità di allineamento delle texture. Valori supportati: `original_image` (dare priorità alla corrispondenza dell’immagine originale), `geometry` (dare priorità alla corrispondenza della geometria)
orientation	stringa	No	`default`	Orientamento del modello. Valori supportati: `default`, `align_image` (allinea al punto di vista dell’immagine in ingresso)
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/image-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "https://example.com/image.png",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/image-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "input": "https://example.com/image.png",
    "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/image-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    input: "https://example.com/image.png",
    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	2003	Il file di input è vuoto	Conferma che il file caricato non sia vuoto o che URL sia accessibile
400	2004	Tipo di file non supportato	Utilizza un formato immagine supportato (PNG, JPEG, WebP)
400	2008	L’input viola le norme sui contenuti	Sostituisci l’immagine di input e rimuovi i contenuti che violano le norme
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 l’input