Segmentação Inteligente

POST /v3/mesh/smartsegment

Pipeline de segmentação inteligente de ponta a ponta. Envie via file_token ou URL público. Suporta caminhos image e model: modelos automáticos de pipeline de imagem e depois segmentos (85 créditos); o pipeline do modelo segmenta um GLB existente (55 créditos).

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

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
seg_type	cadeia	Sim	-	Tipo de segmentação: `image` (pipeline de imagem, 85 créditos) / `model` (pipeline de modelo, 55 créditos)
input	cadeia	Sim	-	Fonte de entrada: `file_token` (de `/v3/files` ou `/v3/files/presign`) ou um URL público
granularity	cadeia	Não	`medium`	Granularidade de segmentação: `coarse` / `medium` / `fine`
hint	cadeia	Não	-	Dica opcional para ajudar a identificar peças a serem segmentadas
transform	número[]	Condicional	-	Obrigatório quando `seg_type=model`. Matriz de transformação 4 × 4 da coluna principal (16 pontos flutuantes)

seg_type e restrições de formato

seg_type	entrada	Formato	Extra necessário	Créditos	Tipo de resposta
`image`	Imagem file_token ou URL	PNG / JPEG / WebP	Nenhum	85	`smartsegment_image`
`model`	Modelo 3D file_token ou URL	Somente GLB	`transform`	55	`smartsegment_model`

Limite de formato seg_type=model: A entrada do modelo deve ser GLB (binário glTF). Arquivos não GLB retornam um erro de parâmetro.

transform é uma matriz 4×4 de coluna principal. Matriz de identidade comum:

JSON

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

Exemplos de solicitação

curl — Imagem (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 + transformação)

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

Resposta

Crie sucesso

JSON

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

Resultado da tarefa (sucesso)

Enquete com o padrão 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 resposta

Parâmetro	Tipo	Descrição
code	inteiro	Código de status. `0` indica sucesso
data.task_id	cadeia	Tarefa exclusiva ID usada para pesquisar o progresso e o resultado
data.output.prompt	cadeia	Etiquetas em inglês separadas por vírgula, geradas automaticamente
data.output.mask_url	cadeia	CDN-assinado URL da máscara semântica PNG
data.output.seg_model_url	cadeia	CDN-URL assinado do modelo GLB segmentado
data.output.seg_task_id	cadeia	Subtarefa interna mesh_segmentation ID
data.output.model_task_id	cadeia	Subtarefa interna image_to_model / import_model ID

Códigos de erro

Código de status HTTP	Código de erro	Descrição	Recomendação
429	2000	Limite de simultaneidade de geração excedido	Reduza a taxa de solicitações e tente novamente mais tarde
400	1004	Erro de parâmetro inválido (formato inválido, não GLB, transformação ausente, etc.)	Verifique `seg_type` / `input` / `transform`
402	2001	Créditos insuficientes	Recarregue os créditos e tente novamente
401	4000	Falha na autenticação	Verifique API Key