Segmentazione intelligente

POST /v3/mesh/smartsegment

Pipeline di segmentazione intelligente end-to-end. Invia tramite file_token o URL pubblico. Supporta percorsi immagine e modello: modelli automatici della pipeline di immagini e quindi segmenti (85 crediti); il modello di pipeline segmenta uno GLB esistente (55 crediti).

Differenza da /v3/mesh/segment: SmartSegment è una pipeline completa (asset → modellazione automatica → segmentazione). /v3/mesh/segment segmenta solo un modello esistente.

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
seg_type	stringa	Sì	—	Tipo di segmentazione: `image` (pipeline di immagini, 85 crediti) / `model` (pipeline di modelli, 55 crediti)
input	stringa	Sì	—	Sorgente di ingresso: `file_token` (da `/v3/files` o `/v3/files/presign`) o URL pubblico
granularity	stringa	No	`medium`	Granularità della segmentazione: `coarse` / `medium` / `fine`
hint	stringa	No	—	Suggerimento facoltativo per identificare le parti da segmentare
transform	numero[]	Condizionale	—	Richiesto quando `seg_type=model`. Matrice di trasformazione 4×4 della colonna principale (16 float)

seg_type e vincoli di formato

seg_type	ingresso	Formato	Extra richiesto	Crediti	Tipo di risposta
`image`	Immagine file_token o URL	PNG / JPEG / WebP	Nessuno	85	`smartsegment_image`
`model`	Modello 3D file_token o URL	Solo GLB	`transform`	55	`smartsegment_model`

Limite formato seg_type=model: l’input del modello deve essere GLB (binario glTF). I file non GLB restituiscono un errore di parametro.

transform è una matrice 4×4 con colonna principale. Matrice di identità comune:

JSON

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

Richiedi esempi

curl — Immagine (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 — Modello (URL + trasformazione)

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

Risposta

Crea successo

JSON

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

Risultato dell’attività (successo)

Sondaggio con lo 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"
  }
}

Campi di risposta

Parametro	Digitare	Descrizione
code	intero	Codice di stato. `0` indica successo
data.task_id	stringa	Compito unico ID utilizzato per sondare progressi e risultati
data.output.prompt	stringa	Etichette in inglese separate da virgole, generate automaticamente
data.output.mask_url	stringa	CDN-firmato URL della maschera semantica PNG
data.output.seg_model_url	stringa	CDN-firmato URL del modello segmentato GLB
data.output.seg_task_id	stringa	Attività secondaria mesh_segmentation interna ID
data.output.model_task_id	stringa	Attività secondaria interna image_to_model / import_model ID

Codici di errore

HTTP Codice di stato	Codice errore	Descrizione	Raccomandazione
429	2000	Limite di concorrenza di generazione superato	Ridurre la frequenza delle richieste e riprovare più tardi
400	1004	Errore di parametro non valido (formato non valido, non GLB, trasformazione mancante, ecc.)	Controllare `seg_type` / `input` / `transform`
402	2001	Crediti insufficienti	Ricaricare i crediti e riprovare
401	4000	Autenticazione non riuscita	Controlla API Key