Tripo-Smart Segmentation

Updated at:

Tripo Smart Segmentation provides an end-to-end segmentation pipeline. It takes an image or a 3D model in GLB format as input and outputs a segmented 3D model. Unlike Mesh Segmentation, which only segments existing models, Smart Segmentation includes automatic modeling.

ImportantThis document applies only to the China (Beijing) region. Use an API key from this region.

Prerequisites

  1. Enable the service: Go to the Alibaba Cloud Model Studio console, search for "Tripo", find the Tripo model card, and click Enable Now. In the dialog box, confirm the authorization.
  2. Configure your API key: Select a region, get an API key, and then configure the API key as an environment variable.

HTTP calls

The API uses asynchronous calls. The process involves two steps: create a task and then poll for the result.

Step 1: Create a task

China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation

Replace {WorkspaceId} with your actual workspace ID.

Note

  • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
  • For guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Request headers

Content-Type string (Required)

The content type of the request. Must be application/json.

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

X-DashScope-Async string (Required)

Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model string (Required)

The model name. Fixed value: Tripo/Tripo-SmartSegmentation.

input object (Required)

The model input.

Properties

seg_type string (Required)

The input type. Valid values:

  • image: Uses an image as input. You must also pass image. PNG, JPEG, and WebP formats are supported.
  • model: Uses a 3D model as input. You must also pass model_url and parameters.transform. Only the GLB format is supported.

image string (Conditionally required)

The public URL of the input image. PNG, JPEG, and WebP formats are supported. The image cannot exceed 20 MB. The resolution is not limited. Required only when seg_type is image.

model_url string (Conditionally required)

The public URL of the model file. Only the GLB format is supported. A non-GLB file returns a 400 error. The file cannot exceed 150 MB. Required only when seg_type is model.

parameters object (Optional)

The segmentation parameters.

Properties

granularity string (Optional)

The segmentation granularity. Valid values:

  • coarse: Coarse. Outputs 2 to 3 major categories, such as person and clothing.
  • medium: Default value. Outputs 4 to 8 objects or parts, such as person, top, pants, shoes, and bag.
  • fine: Fine. Outputs 9 to 52 detailed parts, such as face, hair, left arm, and right arm.

hint string (Optional)

A prompt that helps identify the parts to segment. The length and language are not limited. Keep it short and clear, for example, "separate the cup body from the lid".

transform array[number] (Conditionally required)

A 4×4 column-major transformation matrix that must consist of exactly 16 floating-point numbers. The element values are not limited. Required only when seg_type is model.

If this parameter is not passed or does not contain exactly 16 elements, a 400 error is returned. This parameter is ignored when seg_type is image.

Example of an identity matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1].

Image input

# The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "Tripo/Tripo-SmartSegmentation",
    "input": {
        "seg_type": "image",
        "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/liafix/tripo-images-1.png"
    },
    "parameters": {
        "hint": "wheel"
    }
}'

Model input

You must also pass parameters.transform.

# The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "Tripo/Tripo-SmartSegmentation",
    "input": {
        "seg_type": "model",
        "model_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260507/ffaaxt/tripo-text-to-3d-result.glb"
    },
    "parameters": {
        "transform": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
    }
}'

Response parameters

output object

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Successful response

Save the task_id to query the task status and result.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Step 2: Query the task result

China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • Polling recommendation: Smart segmentation may take several minutes. We recommend using a polling mechanism: query 10 seconds after submitting the task, and then every 15 to 30 seconds.
  • Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
  • Task ID validity: The task ID is valid for 24 hours. After this period, you can no longer query the result, and the API returns the task status as UNKNOWN.
  • RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure asynchronous task callbacks.
  • More operations: To query tasks in batches or cancel a task, see Manage Asynchronous Tasks.

Request parameters

Request headers

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters

task_id string (Required)

The ID of the task.

Query task result

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours. Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output object

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
  • The status of the first query is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the URL of the segmented 3D model.
  • If the status is FAILED, check the error message and retry.
  • If the status is CANCELED, the task was canceled. To continue, submit a new task.
  • If the status is UNKNOWN, the task does not exist or its status is unknown. This can occur if the task_id does not exist or has exceeded its 24-hour validity period.

submit_time string

The time when the task was submitted. Format: YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task started running. Format: YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. Format: YYYY-MM-DD HH:mm:ss.SSS.

results array

The list of segmentation results. Returned only when task_status is SUCCEEDED. Each URL is a signed temporary link that is valid for 2 hours. Please download it promptly.

Properties

seg_model_url string

The URL of the segmented 3D model.

mask_url string

The URL of the 2D segmentation mask image.

prompt string

The names of the identified parts, separated by commas.

model_task_id string

The ID of the internal 3D model subtask. When seg_type is image, it is an image-to-3D subtask. When seg_type is model, it is a model import subtask. It can be used as the original_model_task_id of models such as Tripo-Texturing, Tripo-Retopology, and Tripo-Auto Rigging under the same account.

seg_task_id string

The ID of the internal mesh segmentation subtask. It can be used as the original_model_task_id of Tripo-Mesh Completion under the same account, or used together with part_names in Tripo-Texturing and Tripo-Retopology.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

The output statistics. Returned only when the task succeeds.

Properties

3d_task_type string

The task type. Fixed to smart-segmentation for smart segmentation.

credits_consumed integer

The credits consumed by the task, which equal seg_type.

seg_type integer

The credits consumed by smart segmentation, calculated based on the input type (image or model).

Task succeeded

{
    "request_id": "486ab449-fbdc-9cae-a14f-xxxxxx",
    "output": {
        "task_id": "1b690d69-87df-4237-a023-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-10-19 10:02:22.318",
        "scheduled_time": "2026-10-19 10:02:22.368",
        "end_time": "2026-10-19 10:06:27.092",
        "results": [
            {
                "model_task_id": "2bf3a129-220d-461b-b996-xxxxxx",
                "mask_url": "https://openapi.cdn.tripo3d.com/xxxx/mask.png?auth_key=xxxx",
                "seg_task_id": "9a060088-0280-4c62-ac58-xxxxxx",
                "seg_model_url": "https://openapi.cdn.tripo3d.com/xxxx/segment/tripo_mesh_seg_xxxx.glb?auth_key=xxxx",
                "prompt": "face, hair, ears, armor, cloak, quiver, arrows"
            }
        ]
    },
    "usage": {
        "3d_task_type": "smart-segmentation",
        "credits_consumed": 85,
        "seg_type": 85
    }
}

Task failed

If the task fails, task_status is set to FAILED, and an error code and message are returned. See Error codes.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-xxxxxx",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The parameter is invalid xxxxxx"
    }
}

Task query expired

The task_id is valid for queries for 24 hours. After this period, the following response is returned.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Error messages

If the model call fails and returns an error message, see Error messages for solutions.