Tripo3D

Mesh Segmentation

http
Base URL: https://openapi.tripo3d.ai/v3
Endpoint: POST /mesh/segment
Perform semantic segmentation on a 3D model and automatically split it into parts. Supports v1 (geometry-based, default) and v2 (semantic labeling + geometry, Beta).
Note
  • This endpoint requires an API Key. Include it in the Authorization header as Bearer {api_key}.
  • This is an asynchronous API. After submitting the request, use the Task Query API to poll for results, or configure a Webhook to receive automatic notifications when the task completes.

Request Parameters

Request Body

inputstringRequired
Model source. Accepts task_id, file_token, or URL. Accepts the following input types:
Choose exactly one of the following — do not pass multiple types simultaneously.
  • task_id — The task ID returned by a previous 3D generation task (text_to_model, image_to_model, or multiview_to_model). The system automatically uses the 3D model output from that task.
    Example: task_abc123
  • file_token — Upload a 3D model file via the File Upload API first, then pass the returned token.
    Example: file_abc123
  • URL — A publicly accessible direct link to a 3D model file.
    Example: https://example.com/model.glb
Notes
  • Supported formats: GLB, GLTF, FBX, OBJ, STL
  • Max file size: 150 MB
modelstringdefault: v1.0-20250506
Segmentation model version.
  • v1.0-20250506 — default, geometry-based segmentation.
  • v2.0-20260430 Beta — semantic segmentation with labeling.
segmentation_granularitystringdefault: balanced
v2 only. Segmentation granularity.
  • simple
  • balanced — default
  • detailed
split_by_connectivitybooleandefault: true
v2 only. Whether to split by connected components.
ref_imagestring
v2 only. Optional reference image for semantic analysis. Accepts file_token (from file upload) or a public URL.
When ref_image is provided, segmentation_granularity and split_by_connectivity are ignored.
ref_image example: 3D model (.glb) on the left, color-coded segmentation mask (ref_image) on the right

Left: 3D model (.glb)  |  Right: segmentation mask used as ref_image

Examples

Segment (v1)
{
  "input": "task_abc123"}
Segment (v2 + granularity)
{
  "model": "v2.0-20260430",
  "input": "task_abc123",
  "segmentation_granularity": "balanced",
  "split_by_connectivity": true
}
Segment (v2 + ref_image)
{
  "model": "v2.0-20260430",
  "input": "task_abc123",
  "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
Create task
{
  "code": 0,
  "data": {
    "task_id": "task_abc123"}
}
Task result
{
  "code": 0,
  "data": {
    "task_id": "task_def456",
    "type": "mesh_segmentation",
    "status": "success",
    "progress": 100,
    "output": {
      "model_url": "https://cdn.tripo3d.ai/output/mesh_seg.glb",
      "rendered_image_url": "https://cdn.tripo3d.ai/output/mesh_seg.webp"},
    "credits_consumed": 40,
    "created_at": "2026-05-27T02:22:56Z",
    "completed_at": "2026-05-27T02:25:33Z"}
}