Segmentación inteligente

POST /v3/mesh/smartsegment

Canal de segmentación inteligente de un extremo a otro. Envíelo a través de file_token o un URL público. Admite rutas de imagen y modelo: modelos automáticos de canalización de imágenes y luego segmentos (85 créditos); El modelo de tubería segmenta un GLB existente (55 créditos).

Diferencia con /v3/mesh/segment: SmartSegment es una canalización completa (activo → modelado automático → segmentación). /v3/mesh/segment solo segmenta un modelo existente.

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
seg_type	cadena	si	—	Tipo de segmentación: `image` (canalización de imágenes, 85 créditos) / `model` (canalización modelo, 55 créditos)
input	cadena	si	—	Fuente de entrada: `file_token` (de `/v3/files` o `/v3/files/presign`) o un URL público
granularity	cadena	No	`medium`	Granularidad de segmentación: `coarse` / `medium` / `fine`
hint	cadena	No	—	Sugerencia opcional para ayudar a identificar partes para segmentar
transform	numero[]	Condicional	—	Requerido cuando `seg_type=model`. Matriz de transformación 4 × 4 de columna principal (16 flotadores)

seg_type y restricciones de formato

seg_type	entrada	Formato	Se requiere extra	Créditos	Tipo de respuesta
`image`	Imagen file_token o URL	PNG / JPEG / WebP	Ninguno	85	`smartsegment_image`
`model`	Modelo 3D file_token o URL	Sólo GLB	`transform`	55	`smartsegment_model`

Límite de formato seg_type=model: la entrada del modelo debe ser GLB (glTF binario). Los archivos que no son GLB devuelven un error de parámetro.

transform es una matriz de 4 × 4 de columna principal. Matriz de identidad común:

JSON

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

Ejemplos de solicitudes

curl — Imagen (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 — Modelo (URL + transformación)

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

Respuesta

Crear éxito

JSON

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

Resultado de la tarea (éxito)

Encuesta con el estándar 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"
  }
}

Campos de respuesta

Parámetro	Tipo	Descripción
code	entero	Código de estado. `0` indica éxito
data.task_id	cadena	Tarea única ID utilizada para sondear el progreso y el resultado.
data.output.prompt	cadena	Etiquetas en inglés separadas por comas, generadas automáticamente
data.output.mask_url	cadena	CDN-URL firmado de la máscara semántica PNG
data.output.seg_model_url	cadena	CDN-URL firmado del modelo segmentado GLB
data.output.seg_task_id	cadena	Subtarea interna mesh_segmentation ID
data.output.model_task_id	cadena	Subtarea interna image_to_model / import_model ID

Códigos de error

Código de estado HTTP	Código de error	Descripción	Recomendación
429	2000	Se superó el límite de simultaneidad de generación	Reduzca la tasa de solicitudes y vuelva a intentarlo más tarde
400	1004	Error de parámetro no válido (formato no válido, no GLB, falta transformación, etc.)	Compruebe `seg_type` / `input` / `transform`
402	2001	Créditos insuficientes	Recarga créditos y vuelve a intentarlo
401	4000	Error de autenticación	Comprobar API Key