Segmentazione semantica della mesh

POST /v3/mesh/segment

Esegui la segmentazione semantica su un modello 3D e dividi automaticamente il modello in parti semantiche. Supporta v1 (basato sulla geometria, predefinito) e v2 (etichettatura semantica + geometria, Beta).

Differenza da /v3/mesh/smartsegment: questo API segmenta solo un modello esistente. SmartSegment è una pipeline end-to-end (asset → modellazione automatica → segmentazione).

Richiedi parametri

Richiedi intestazioni

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

Richiedi corpo

Parametro	Digitare	Obbligatorio	Predefinito	Descrizione
input	stringa	Sì	—	Fonte del modello. Accetta task_id, file_token o URL
model	stringa	No	`v1.0-20250506`	Versione: `v1.0-20250506` (predefinita) / `v2.0-20260430` (Beta)
segmentation_granularity	stringa	No	`balanced`	Solo v2. Granularità: `simple` / `balanced` / `detailed`
split_by_connectivity	booleano	No	`true`	Solo v2. Indica se effettuare la suddivisione in base ai componenti collegati
ref_image	stringa	No	—	Solo v2. Immagine di riferimento: `file_token` o URL. Quando viene fornito `ref_image`, `segmentation_granularity` e `split_by_connectivity` vengono ignorati

v1 rispetto a v2

Dimensione	v1 (`v1.0-20250506`)	v2 (`v2.0-20260430`, Beta)
Metodo	Geometria/topologia	Etichettatura semantica + geometria
`segmentation_granularity`	Non supportato	`simple` / `balanced` / `detailed`
`split_by_connectivity`	Non supportato	Supportato, predefinito `true`
`ref_image`	Non supportato (errore se impostato)	Opzionale `file_token` o URL

Richiedi esempi

curl — v1 (predefinito)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "task_abc123"}'

curl — v2 (modalità granularità)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "segmentation_granularity": "balanced",
    "split_by_connectivity": true
  }'

curl — v2 (modalità ref_image, granularità e split_by_connectivity ignorati)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

import requests

url = "https://openapi.tripo3d.ai/v3/mesh/segment"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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

const url = "https://openapi.tripo3d.ai/v3/mesh/segment";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    model: "v2.0-20260430",
    input: "task_abc123",
    ref_image: "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  })
});

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

Risposta

Risposta riuscita

JSON

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

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 il risultato della segmentazione

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	1004	Parametro non valido (ad esempio ref_image su v1)	Conferma la versione del modello e la combinazione dei parametri
400	2006	Tipo di attività di origine di input non valido	Confermare che task_id corrisponde a un’attività di modello 3D
400	2007	Lo stato dell’attività di origine non ha esito positivo	Attendi il completamento dell’attività di origine prima di iniziare la segmentazione
403	2010	Crediti insufficienti	Ricaricare i crediti e riprovare