Intelligente Segmentierung

POST /v3/mesh/smartsegment

Durchgängige intelligente Segmentierungspipeline. Senden Sie über file_token oder ein öffentliches URL. Unterstützt sowohl Bild- als auch Modell-Pfade: Bildpipeline modelliert automatisch und segmentiert dann (85 Credits); Modellpipeline segmentiert ein bestehendes GLB (55 Credits).

Unterschied zu /v3/mesh/segment: SmartSegment ist eine vollständige Pipeline (Asset → automatische Modellierung → Segmentierung). /v3/mesh/segment segmentiert nur ein vorhandenes Modell.

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
seg_type	Zeichenfolge	Ja	—	Segmentierungstyp: `image` (Bildpipeline, 85 Credits) / `model` (Modellpipeline, 55 Credits)
input	Zeichenfolge	Ja	—	Eingabequelle: `file_token` (von `/v3/files` oder `/v3/files/presign`) oder ein öffentlicher URL
granularity	Zeichenfolge	Nein	`medium`	Segmentierungsgranularität: `coarse` / `medium` / `fine`
hint	Zeichenfolge	Nein	—	Optionaler Hinweis zur Identifizierung der zu segmentierenden Teile
transform	Nummer[]	Bedingt	—	Erforderlich bei `seg_type=model`. Spaltengroße 4×4-Transformationsmatrix (16 Floats)

seg_type und Formatbeschränkungen

seg_type	Eingabe	Formatieren	Extra erforderlich	Credits	Antworttyp
`image`	Bild file_token oder URL	PNG / JPEG / WebP	Keine	85	`smartsegment_image`
`model`	3D-Modell file_token oder URL	Nur GLB	`transform`	55	`smartsegment_model`

Formatbeschränkung seg_type=model: Modelleingabe muss GLB sein (binäres glTF). Nicht-GLB-Dateien geben einen Parameterfehler zurück.

transform ist eine spaltengroße 4×4-Matrix. Gemeinsame Identitätsmatrix:

JSON

[1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]

Fordern Sie Beispiele an

curl – Bild (file_token)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium",
    "hint": "game character with sword and armor"
  }'

curl – Modell (URL + Transformation)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "model",
    "input": "https://example.com/character.glb",
    "transform": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
    "granularity": "fine",
    "hint": "character body parts"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/mesh/smartsegment"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium"
}

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

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

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    seg_type: "image",
    input: "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    granularity: "medium"
  })
});

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

Antwort

Schaffen Sie Erfolg

JSON

{
  "code": 0,
  "data": {
    "task_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "type": "smartsegment_image",
    "status": "queued"
  }
}

Aufgabenergebnis (Erfolg)

Umfrage mit dem Standard API GET /v3/tasks/{task_id}.

JSON

{
  "code": 0,
  "data": {
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "smartsegment_image",
    "status": "success",
    "progress": 100,
    "input": {
      "granularity": "medium"
    },
    "output": {
      "prompt": "head, body, left arm, right arm, legs",
      "mask_url": "https://cdn.tripo3d.ai/.../mask.png?auth_key=...",
      "seg_model_url": "https://cdn.tripo3d.ai/.../model.glb?auth_key=...",
      "seg_task_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "model_task_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
    },
    "credits_consumed": 85.00,
    "created_at": "2026-06-30T09:08:14.882623Z",
    "completed_at": "2026-06-30T09:14:15.183547Z"
  }
}

Antwortfelder

Parameter	Typ	Beschreibung
code	ganze Zahl	Statuscode. `0` zeigt Erfolg an
data.task_id	Zeichenfolge	Einzigartige Aufgabe ID zur Abfrage von Fortschritt und Ergebnis
data.output.prompt	Zeichenfolge	Automatisch generierte, durch Kommas getrennte englische Labels
data.output.mask_url	Zeichenfolge	CDN-signiertes URL der semantischen Maske PNG
data.output.seg_model_url	Zeichenfolge	CDN-signiertes URL des segmentierten GLB-Modells
data.output.seg_task_id	Zeichenfolge	Interne Unteraufgabe mesh_segmentation ID
data.output.model_task_id	Zeichenfolge	Interne Unteraufgabe image_to_model / import_model ID

Fehlercodes

HTTP Statuscode	Fehlercode	Beschreibung	Empfehlung
429	2000	Das Limit für die Parallelität der Generierung wurde überschritten	Reduzieren Sie die Anforderungsrate und versuchen Sie es später erneut
400	1004	Fehler aufgrund eines ungültigen Parameters (ungültiges Format, Nicht-GLB, fehlende Transformation usw.)	Überprüfen Sie `seg_type` / `input` / `transform`
402	2001	Unzureichende Credits	Guthaben aufladen und erneut versuchen
401	4000	Die Authentifizierung ist fehlgeschlagen	Überprüfen Sie API Key