Segmentation sémantique du maillage

POST /v3/mesh/segment

Effectuez une segmentation sémantique sur un modèle 3D et divisez automatiquement le modèle en parties sémantiques. Prend en charge v1 (basé sur la géométrie, par défaut) et v2 (étiquetage sémantique + géométrie, Beta).

Différence avec /v3/mesh/smartsegment : ce API segmente uniquement un modèle existant. SmartSegment est un pipeline de bout en bout (actif → modélisation automatique → segmentation).

Paramètres de la demande

En-têtes de demande

Paramètre	Tapez	Obligatoire	Par défaut	Descriptif
Content-Type	chaîne	Oui	—	`application/json`
Authorization	chaîne	Oui	—	`Bearer {api_key}`

Corps de la demande

Paramètre	Tapez	Obligatoire	Par défaut	Descriptif
input	chaîne	Oui	—	Source du modèle. Accepte task_id, file_token ou URL
model	chaîne	Non	`v1.0-20250506`	Version : `v1.0-20250506` (par défaut) / `v2.0-20260430` (Bêta)
segmentation_granularity	chaîne	Non	`balanced`	v2 uniquement. Granularité : `simple` / `balanced` / `detailed`
split_by_connectivity	booléen	Non	`true`	v2 uniquement. S’il faut diviser par composants connectés
ref_image	chaîne	Non	—	v2 uniquement. Image de référence : `file_token` ou URL. Lorsque `ref_image` est fourni, `segmentation_granularity` et `split_by_connectivity` sont ignorés

v1 contre v2

Dimensions	v1 (`v1.0-20250506`)	v2 (`v2.0-20260430`, bêta)
Méthode	Géométrie / topologie	Étiquetage sémantique + géométrie
`segmentation_granularity`	Non pris en charge	`simple` / `balanced` / `detailed`
`split_by_connectivity`	Non pris en charge	Pris en charge, `true` par défaut
`ref_image`	Non pris en charge (erreur si défini)	`file_token` ou URL en option

Exemples de demande

curl — v1 (par défaut)

Bash

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 (mode granularité)

Bash

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 (mode ref_image, granularité et split_by_connectivity ignorés)

Bash

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

Réponse

Réponse réussie

JSON

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

Champs de réponse

Paramètre	Tapez	Descriptif
code	entier	Code d’état. `0` indique le succès
data.task_id	chaîne	Identifiant de tâche unique utilisé pour interroger la progression et le résultat de la segmentation

Codes d’erreur

Code d’état HTTP	Code d’erreur	Descriptif	Recommandation
429	2000	Limite de génération dépassée	Réduisez le taux de demandes et réessayez plus tard
400	2002	Paramètre de requête non pris en charge	Vérifier les noms des paramètres du corps de la requête et les plages de valeurs
400	1004	Paramètre invalide (par exemple ref_image sur v1)	Confirmer la version du modèle et la combinaison de paramètres
400	2006	Type de tâche source d’entrée non valide	Confirmer que le task_id correspond à une tâche de modèle 3D
400	2007	L’état de la tâche source n’a pas réussi	Attendez la fin de la tâche source avant de démarrer la segmentation
403	2010	Crédits insuffisants	Recharger les crédits et réessayer