Segmentación semántica de malla

POST /v3/mesh/segment

Realice una segmentación semántica en un modelo 3D y divida automáticamente el modelo en partes semánticas. Admite v1 (basado en geometría, predeterminado) y v2 (etiquetado semántico + geometría, Beta).

Diferencia con /v3/mesh/smartsegment: este API solo segmenta un modelo existente. SmartSegment es una canalización de un extremo a otro (activo → modelado automático → segmentación).

Solicitar parámetros

Encabezados de solicitud

Parámetro	Tipo	Requerido	Predeterminado	Descripción
Content-Type	cadena	si	—	`application/json`
Authorization	cadena	si	—	`Bearer {api_key}`

Cuerpo de solicitud

Parámetro	Tipo	Requerido	Predeterminado	Descripción
input	cadena	si	—	Fuente del modelo. Acepta task_id, file_token o URL
model	cadena	No	`v1.0-20250506`	Versión: `v1.0-20250506` (predeterminado) / `v2.0-20260430` (Beta)
segmentation_granularity	cadena	No	`balanced`	Solo v2. Granularidad: `simple` / `balanced` / `detailed`
split_by_connectivity	booleano	No	`true`	Solo v2. Ya sea para dividir por componentes conectados
ref_image	cadena	No	—	Solo v2. Imagen de referencia: `file_token` o URL. Cuando se proporciona `ref_image`, se ignoran `segmentation_granularity` y `split_by_connectivity`

v1 y v2

Dimensión	v1 (`v1.0-20250506`)	v2 (`v2.0-20260430`, Beta)
Método	Geometría / topología	Etiquetado semántico + geometría
`segmentation_granularity`	No compatible	`simple` / `balanced` / `detailed`
`split_by_connectivity`	No compatible	Compatible, predeterminado `true`
`ref_image`	No compatible (error si está configurado)	Opcional `file_token` o URL

Ejemplos de solicitudes

curl — v1 (predeterminado)

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 (modo de granularidad)

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 (modo ref_image, granularidad y split_by_connectivity ignorados)

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

Respuesta

Respuesta exitosa

JSON

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

Campos de respuesta

Parámetro	Tipo	Descripción
code	entero	Código de estado. `0` indica éxito
data.task_id	cadena	Identificador de tarea único utilizado para sondear el progreso y el resultado de la segmentación

Códigos de error

Código de estado HTTP	Código de error	Descripción	Recomendación
429	2000	Límite de generación excedido	Reduzca la tasa de solicitudes y vuelva a intentarlo más tarde
400	2002	Parámetro de solicitud no admitido	Verifique los nombres de los parámetros del cuerpo de la solicitud y los rangos de valores
400	1004	Parámetro no válido (por ejemplo, ref_image en v1)	Confirmar la versión del modelo y la combinación de parámetros
400	2006	Tipo de tarea de fuente de entrada no válida	Confirmar que el task_id corresponde a una tarea de modelo 3D
400	2007	El estado de la tarea de origen no es exitoso	Espere hasta que se complete la tarea de origen antes de comenzar la segmentación
403	2010	Créditos insuficientes	Recarga créditos y vuelve a intentarlo