# 智能分割
**Base URL:** `https://openapi.tripo3d.ai/v3`
**Endpoint:** `POST /mesh/smartsegment`
端到端智能分割 pipeline。通过 `file_token` 或 URL 提交,支持 `seg_type=image` 与 `seg_type=model`(仅 GLB)。与[网格分割](https://developers.tripo3d.ai/zh/docs/mesh-segment)的区别:SmartSegment 含自动建模;`/v3/mesh/segment` 仅对已有模型分割。
## Request Parameters
### seg_type
- **Type:** string
- **Required:** 必选
分割类型。
- `image`:图片 pipeline(PNG / JPEG / WebP)
- `model`:模型 pipeline(**仅 GLB**;须传 `transform`)
### input
- **Type:** string
- **Required:** 必选
输入源。接受同一 API Key 下已成功任务的 `task_id`、`file_token`([文件上传](https://developers.tripo3d.ai/zh/docs/files) 或 [大文件直传](https://developers.tripo3d.ai/zh/docs/files-presign)返回)或外部 URL。`seg_type=model` 时文件**必须为 GLB**。
传 `task_id` 时:`seg_type=image` 使用该任务的输出图片(如文生图、文生模型的生成图);`seg_type=model` 使用其 GLB 模型(如文生模型、图生模型)。错误码:`2001` 该 API Key 下找不到此任务,`2007` 任务未成功,`2006` 任务没有可用的图片或 GLB 模型(其他格式请先转换为 GLB)。
### granularity
- **Type:** string
- **Required:** 可选
- **Default:** `medium`
分割粒度。
- `coarse`
- `medium`:默认
- `fine`
### hint
- **Type:** string
- **Required:** 可选
可选提示词,辅助识别需要分割的部件。
### transform
- **Type:** number[]
- **Required:** 条件必填
**`seg_type=model` 时必填**。列主序 4×4 变换矩阵(16 个 float)。单位矩阵示例:`[1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]`
## Request Example
### 图片 pipeline
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/mesh/smartsegment \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"seg_type": "image",
"input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"granularity": "medium",
"hint": "game character with sword and armor"
}'
```
### 模型 pipeline
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/mesh/smartsegment \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"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"
}'
```
## Response Example
### 创建任务
```json
{
"code": 0,
"data": {
"task_id": "123e4567-e89b-42d3-a456-426614174000"
}
}
```
### 任务结果
```json
{
"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"
}
}
```
Base URL: https://openapi.tripo3d.ai/v3
Endpoint: POST /mesh/smartsegment
端到端智能分割 pipeline。通过
file_token 或 URL 提交,支持
seg_type=image 与
seg_type=model(仅 GLB)。与
网格分割的区别:SmartSegment 含自动建模;
/v3/mesh/segment 仅对已有模型分割。
- 此接口需要 API Key 认证。请在 Authorization 请求头中传入 Bearer {api_key}。
- 此接口为异步 API。提交请求后,请使用 任务查询接口 轮询获取结果,或配置 Webhook 接收任务完成时的自动通知。
请求参数
请求体
seg_typestring必选
分割类型。
image:图片 pipeline(PNG / JPEG / WebP)model:模型 pipeline(仅 GLB;须传 transform)
inputstring必选
输入源。接受同一 API Key 下已成功任务的
task_id、
file_token(
文件上传 或
大文件直传返回)或外部 URL。
seg_type=model 时文件必须为 GLB。
传 task_id 时:seg_type=image 使用该任务的输出图片(如文生图、文生模型的生成图);seg_type=model 使用其 GLB 模型(如文生模型、图生模型)。错误码:2001 该 API Key 下找不到此任务,2007 任务未成功,2006 任务没有可用的图片或 GLB 模型(其他格式请先转换为 GLB)。
granularitystring默认值: medium
hintstring
可选提示词,辅助识别需要分割的部件。
transformnumber[]条件必选
seg_type=model 时必填。列主序 4×4 变换矩阵(16 个 float)。单位矩阵示例:[1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]
示例
{
"seg_type": "image",
"input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"granularity": "medium",
"hint": "game character with sword and armor"}
{
"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"}
{
"code": 0,
"data": {
"task_id": "123e4567-e89b-42d3-a456-426614174000"}
}
{
"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"}
}