Segmentation intelligente

POST /v3/mesh/smartsegment

Pipeline de segmentation intelligente de bout en bout. Soumettez via file_token ou un URL public. Prend en charge les chemins image et modèle : le pipeline d’images modélise automatiquement puis segmente (85 crédits) ; un pipeline modèle segmente un GLB existant (55 crédits).

Différence avec /v3/mesh/segment : SmartSegment est un pipeline complet (actif → modélisation automatique → segmentation). /v3/mesh/segment segmente uniquement un modèle existant.

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
seg_type	chaîne	Oui	—	Type de segmentation : `image` (pipeline d’images, 85 crédits) / `model` (pipeline de modèles, 55 crédits)
input	chaîne	Oui	—	Source d’entrée : `file_token` (depuis `/v3/files` ou `/v3/files/presign`) ou un URL public
granularity	chaîne	Non	`medium`	Granularité de segmentation : `coarse` / `medium` / `fine`
hint	chaîne	Non	—	Astuce facultative pour aider à identifier les pièces à segmenter
transform	numéro[]	Conditionnel	—	Obligatoire lorsque `seg_type=model`. Matrice de transformation 4 × 4 en colonne majeure (16 flotteurs)

seg_type et contraintes de format

seg_type	entrée	Formater	Supplément requis	Crédits	Type de réponse
`image`	Image file_token ou URL	PNG / JPEG / WebP	Aucun	85	`smartsegment_image`
`model`	Modèle 3D file_token ou URL	GLB uniquement	`transform`	55	`smartsegment_model`

Limite de format seg_type=model : l’entrée du modèle doit être GLB (binaire glTF). Les fichiers non-GLB renvoient une erreur de paramètre.

transform est une matrice 4×4 à colonnes majeures. Matrice d’identité commune :

JSON

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

Exemples de demande

curl — Image (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 — Modèle (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);

Réponse

Créer du succès

JSON

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

Résultat de la tâche (succès)

Sondage avec le 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"
  }
}

Champs de réponse

Paramètre	Tapez	Descriptif
code	entier	Code d’état. `0` indique le succès
data.task_id	chaîne	Tâche unique ID utilisée pour interroger la progression et le résultat
data.output.prompt	chaîne	Étiquettes en anglais séparées par des virgules, générées automatiquement
data.output.mask_url	chaîne	CDN-signé URL du masque sémantique PNG
data.output.seg_model_url	chaîne	CDN-signé URL du modèle segmenté GLB
data.output.seg_task_id	chaîne	Sous-tâche interne mesh_segmentation ID
data.output.model_task_id	chaîne	Sous-tâche interne image_to_model / import_model ID

Codes d’erreur

Code d’état HTTP	Code d’erreur	Descriptif	Recommandation
429	2000	Limite de simultanéité de génération dépassée	Réduisez le taux de requêtes et réessayez plus tard
400	1004	Erreur de paramètre invalide (format invalide, non-GLB, transformation manquante, etc.)	Vérifiez `seg_type` / `input` / `transform`
402	2001	Crédits insuffisants	Recharger les crédits et réessayer
401	4000	L’authentification a échoué	Vérifiez API Key