Tripo3D

Smart Segmentation

http
Base URL: https://openapi.tripo3d.com/v3
Endpoint: POST /mesh/smartsegment
End-to-end smart segmentation pipeline. Submit via file_token or URL. Supports seg_type=image and seg_type=model (GLB only). Differs from Mesh Segmentation: SmartSegment includes auto modeling; /v3/mesh/segment only segments an existing model.
Note
  • This endpoint requires an API Key. Include it in the Authorization header as Bearer {api_key}. Example identifiers are illustrative; replace them with values returned by your requests.
  • 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

seg_typestringRequired
Segmentation pipeline type.
  • image — image pipeline (PNG / JPEG / WebP)
  • model — model pipeline (GLB only; transform required)
inputstringRequired
Input source. Accepts the task_id of a successful task created with the same API key, a file_token (from File Upload or Presign Upload), or a public URL.
For seg_type=model, the file must be GLB.
With a task_id: seg_type=image uses the task's output image (e.g. text-to-image, or the generated image of text-to-model); seg_type=model uses its GLB model (e.g. text-to-model, image-to-model). Errors: 2001 task not found under this API key, 2007 task has not succeeded, 2006 the task has no usable image / GLB model (convert other formats to GLB first).
granularitystringdefault: medium
Segmentation granularity.
  • coarse
  • medium — default
  • fine
hintstring
Optional hint text to help identify parts that should be segmented.
transformnumber[]Conditional
Required when seg_type=model. Column-major 4×4 transform matrix (16 floats). Identity example: [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]

Examples

Image pipeline
{
  "seg_type": "image",
  "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "granularity": "medium",
  "hint": "game character with sword and armor"}
Model pipeline
{
  "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"}
Create task
{
  "code": 0,
  "data": {
    "task_id": "123e4567-e89b-42d3-a456-426614174000"}
}
Task result
{
  "code": 0,
  "data": {
    "task_id": "123e4567-e89b-42d3-a456-426614174000",
    "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/output/mask.png",
      "seg_model_url": "https://cdn.tripo3d.ai/output/seg_model.glb",
      "seg_task_id": "b6af63be-30d8-4cc0-b8d8-79be093e0123",
      "model_task_id": "c6af63be-30d8-4cc0-b8d8-79be093e0456"},
    "credits_consumed": 85.00,
    "created_at": "2026-06-30T09:08:14Z",
    "completed_at": "2026-06-30T09:14:15Z"}
}
PreviousSegmentationNextMesh Complete