Semantische Mesh-Segmentierung

POST /v3/mesh/segment

Führen Sie eine semantische Segmentierung an einem 3D-Modell durch und teilen Sie das Modell automatisch in semantische Teile auf. Unterstützt v1 (geometriebasiert, Standard) und v2 (semantische Beschriftung + Geometrie, Beta).

Unterschied zu /v3/mesh/smartsegment: Dieser API segmentiert nur ein vorhandenes Modell. SmartSegment ist eine End-to-End-Pipeline (Asset → automatische Modellierung → Segmentierung).

Anforderungsparameter

Anforderungsheader

Parameter	Typ	Erforderlich	Standard	Beschreibung
Content-Type	Zeichenfolge	Ja	—	`application/json`
Authorization	Zeichenfolge	Ja	—	`Bearer {api_key}`

Anforderungstext

Parameter	Typ	Erforderlich	Standard	Beschreibung
input	Zeichenfolge	Ja	—	Modellquelle. Akzeptiert task_id, file_token oder URL
model	Zeichenfolge	Nein	`v1.0-20250506`	Version: `v1.0-20250506` (Standard) / `v2.0-20260430` (Beta)
segmentation_granularity	Zeichenfolge	Nein	`balanced`	Nur v2. Granularität: `simple` / `balanced` / `detailed`
split_by_connectivity	Boolescher Wert	Nein	`true`	Nur v2. Ob nach verbundenen Komponenten aufgeteilt werden soll
ref_image	Zeichenfolge	Nein	—	Nur v2. Referenzbild: `file_token` oder URL. Wenn `ref_image` bereitgestellt wird, werden `segmentation_granularity` und `split_by_connectivity` ignoriert

v1 vs. v2

Dimension	v1 (`v1.0-20250506`)	v2 (`v2.0-20260430`, Beta)
Methode	Geometrie / Topologie	Semantische Beschriftung + Geometrie
`segmentation_granularity`	Nicht unterstützt	`simple` / `balanced` / `detailed`
`split_by_connectivity`	Nicht unterstützt	Unterstützt, Standard `true`
`ref_image`	Nicht unterstützt (Fehler, wenn gesetzt)	Optional `file_token` oder URL

Fordern Sie Beispiele an

curl – v1 (Standard)

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 (Granularitätsmodus)

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 (ref_image-Modus, Granularität und split_by_connectivity werden ignoriert)

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);

Antwort

Erfolgreiche Antwort

JSON

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

Antwortfelder

Parameter	Typ	Beschreibung
code	ganze Zahl	Statuscode. `0` zeigt Erfolg an
data.task_id	Zeichenfolge	Eindeutige Aufgabenkennung, die zum Abfragen des Segmentierungsfortschritts und -ergebnisses verwendet wird

Fehlercodes

HTTP Statuscode	Fehlercode	Beschreibung	Empfehlung
429	2000	Generationslimit überschritten	Reduzieren Sie die Anforderungsrate und versuchen Sie es später erneut
400	2002	Nicht unterstützter Anforderungsparameter	Überprüfen Sie die Parameternamen und Wertebereiche des Anforderungshauptteils
400	1004	Ungültiger Parameter (z. B. ref_image auf v1)	Bestätigen Sie Modellversion und Parameterkombination
400	2006	Ungültiger Aufgabentyp der Eingabequelle	Bestätigen Sie, dass task_id einer 3D-Modellaufgabe entspricht
400	2007	Der Status der Quellaufgabe ist nicht erfolgreich	Warten Sie, bis die Quellaufgabe abgeschlossen ist, bevor Sie mit der Segmentierung beginnen
403	2010	Unzureichende Credits	Guthaben aufladen und erneut versuchen