Visualizzazione multipla su modello 3D

POST /v3/generation/multiview-to-model

Genera un modello 3D da immagini multivista.

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
inputs	oggetto[] \	corda[4]	Sì	-
model	stringa	No	`v3.1-20260211`	Versione del modello AI. Valori supportati: `v3.1-20260211` (predefinito; il più recente, qualità migliore), `v3.0-20250812` (stabile, funzionalità avanzate), `v2.5-20250123` (equilibrato)
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 >= v3.0-20250812: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

formati di input

chiave di visualizzazione (consigliata)

Ogni elemento dell’array è un oggetto con esattamente una chiave tra front, left, back o right. L’ordine non ha importanza; il server viene canonicalizzato in [front, left, back, right]. front è richiesto; almeno due visualizzazioni devono essere non vuote.

Con URL:

JSON

{
  "inputs": [
    {"front": "https://example.com/front.png"},
    {"back": "https://example.com/back.png"},
    {"right": "https://example.com/right.png"}
  ],
  "model": "v3.1-20260211",
  "texture": false,
  "geometry_quality": "detailed"
}

Con file_tokens (ottenuto tramite il file di caricamento API):

JSON

{
  "inputs": [
    {"front": "3154b4b0-4647-4032-aa82-827441ae92ef"},
    {"back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},
    {"right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}
  ],
  "model": "v3.1-20260211",
  "texture": false,
  "geometry_quality": "detailed"
}

posizionale ereditario

Esattamente quattro corde in ordine [front, left, back, right]. Utilizza una stringa vuota "" per saltare una vista.

JSON

{
  "inputs": [
    "file_front_token",
    "",
    "https://example.com/back.png",
    "https://example.com/right.png"
  ]
}

task_id (riutilizza attività di visualizzazione multipla)

Passa lo ID di un’attività generate_multiview_image o edit_multiview_image precedente per riutilizzare l’output a 4 visualizzazioni per la generazione 3D. inputs deve essere un array a elemento singolo con un oggetto task_id: non combinare con chiavi di visualizzazione o slot posizionali. L’attività di origine deve essere nello stato success.

JSON

{
  "inputs": [
    {"task_id": "550e8400-e29b-41d4-a716-446655440000"}
  ],
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true
}

Richiedi esempi

curl -X POST https://openapi.tripo3d.ai/v3/generation/multiview-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "inputs": [
      "https://example.com/front.png",
      "https://example.com/back.png",
      "https://example.com/left.png",
      "https://example.com/right.png"
    ],
    "model": "v3.1-20260211",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/multiview-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "inputs": [
        "https://example.com/front.png",
        "https://example.com/back.png",
        "https://example.com/left.png",
        "https://example.com/right.png"
    ],
    "model": "v3.1-20260211",
    "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/multiview-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    inputs: [
      "https://example.com/front.png",
      "https://example.com/back.png",
      "https://example.com/left.png",
      "https://example.com/right.png"
    ],
    model: "v3.1-20260211",
    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