Segmentação Semântica de Malha

POST /v3/mesh/segment

Execute a segmentação semântica em um modelo 3D e divida automaticamente o modelo em partes semânticas. Suporta v1 (baseado em geometria, padrão) e v2 (rotulagem semântica + geometria, Beta).

Diferença de /v3/mesh/smartsegment: este API segmenta apenas um modelo existente. SmartSegment é um pipeline ponta a ponta (ativo → modelagem automática → segmentação).

Parâmetros de solicitação

Solicitar cabeçalhos

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
Content-Type	cadeia	Sim	-	`application/json`
Authorization	cadeia	Sim	-	`Bearer {api_key}`

Corpo da Solicitação

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
input	cadeia	Sim	-	Fonte do modelo. Aceita task_id, file_token ou URL
model	cadeia	Não	`v1.0-20250506`	Versão: `v1.0-20250506` (padrão) / `v2.0-20260430` (Beta)
segmentation_granularity	cadeia	Não	`balanced`	Somente v2. Granularidade: `simple` / `balanced` / `detailed`
split_by_connectivity	booleano	Não	`true`	Somente v2. Se deve ser dividido por componentes conectados
ref_image	cadeia	Não	-	Somente v2. Imagem de referência: `file_token` ou URL. Quando `ref_image` é fornecido, `segmentation_granularity` e `split_by_connectivity` são ignorados

v1 vs v2

Dimensão	v1 (`v1.0-20250506`)	v2 (`v2.0-20260430`, Beta)
Método	Geometria/topologia	Rotulagem semântica + geometria
`segmentation_granularity`	Não compatível	`simple` / `balanced` / `detailed`
`split_by_connectivity`	Não compatível	Compatível, padrão `true`
`ref_image`	Não suportado (erro se definido)	`file_token` ou URL opcional

Exemplos de solicitação

curl — v1 (padrão)

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

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, granularidade e 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);

Resposta

Resposta bem sucedida

JSON

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

Campos de resposta

Parâmetro	Tipo	Descrição
code	inteiro	Código de status. `0` indica sucesso
data.task_id	cadeia	Identificador de tarefa exclusivo usado para pesquisar o progresso e o resultado da segmentação

Códigos de erro

Código de status HTTP	Código de erro	Descrição	Recomendação
429	2000	Limite de geração excedido	Reduza a taxa de solicitação e tente novamente mais tarde
400	2002	Parâmetro de solicitação não compatível	Verifique os nomes dos parâmetros do corpo da solicitação e os intervalos de valores
400	1004	Parâmetro inválido (por exemplo, ref_image em v1)	Confirme a versão do modelo e a combinação de parâmetros
400	2006	Tipo de tarefa de origem de entrada inválido	Confirme se task_id corresponde a uma tarefa de modelo 3D
400	2007	O status da tarefa de origem não foi bem-sucedido	Aguarde até que a tarefa de origem seja concluída antes de iniciar a segmentação
403	2010	Créditos insuficientes	Recarregue os créditos e tente novamente