Auto Split API

将一个 3D 模型拆分为多个可分别打印的部件——可以自动拆分，也可以按你指定的部件拆分，或按颜色区域拆分——并可选择添加连接件；切割后留下的薄弱区域始终会被加固，以确保每个部件都能被实心打印出来。

拆分结果不会保留输入的 texture。 Auto Split 接受带 texture 的输入，因此你无需使用 should_texture: false 重新生成模型。它会重建切割后的部件，并为每个部件赋予单一的顶点颜色；输入的 texture 贴图不会被带入任何导出格式中。

POST/openapi/v1/print/split

流式获取 Auto Split 任务

此 endpoint 使用 Server-Sent Events（SSE）流式传输 Auto Split 任务的实时更新。

参数

Name
id
Type
path
Description
要流式传输的 Auto Split 任务的唯一标识符。

以 Server-Sent Events 的形式返回 Auto Split 任务对象的流。

每个 message 事件都携带获取 Auto Split 任务返回的完整任务对象，包括 consumed_credits、时间戳以及 prompt_ignored；当任务处于 PENDING 或 IN_PROGRESS 状态时，帧之间会变化的字段是 progress、status、started_at 和 preceding_tasks，而 model_urls、thumbnail_url 和 part_count 会在任务达到 SUCCEEDED 状态后出现。error 事件只携带 status_code 和 message，因此在读取 status 之前应先根据事件名称进行分支处理。

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

The Auto Split Task Object

Auto Split 任务仅携带以下属性。其他任务对象中包含的生成提示词字段（name、object_prompt、texture_prompt 等）、单个 model_url 以及 texture_urls，在拆分任务中永远不会被填充，也不会被返回。随着任务运行而逐步填充的属性（thumbnail_url、model_urls、时间戳）始终存在，只是在有值之前为空，因此这组键在 PENDING 和 SUCCEEDED 之间不会发生变化。

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-可排序的 UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。此值为 print-split。
Name
model_urls
Type
object
Description
指向拆分模型的可下载 URL，每个请求的格式对应一个。支持 scene 对象的格式会将每个部件保留为独立对象；stl 会将它们熔合为一个整体。如果未请求某种格式，则该格式对应的属性将被省略。
- Name
  glb
  Type
  string
  Description
  指向 GLB 格式拆分模型的可下载 URL。
- Name
  obj
  Type
  string
  Description
  指向 OBJ 格式拆分模型的可下载 URL。
- Name
  fbx
  Type
  string
  Description
  指向 FBX 格式拆分模型的可下载 URL。
- Name
  stl
  Type
  string
  Description
  指向 STL 格式拆分模型的可下载 URL。所有部件都会熔合为一个整体；如需分别可选的部件，请请求 3mf。
- Name
  usdz
  Type
  string
  Description
  指向 USDZ 格式拆分模型的可下载 URL。
- Name
  blend
  Type
  string
  Description
  指向 Blender 格式拆分模型的可下载 URL。
- Name
  3mf
  Type
  string
  Description
  指向 3MF 格式拆分模型的可下载 URL。
Name
thumbnail_url
Type
string
Description
指向拆分模型渲染预览图的可下载 URL，其中每个部件以不同颜色显示，采用所请求的 layout。
Name
prompt_ignored
Type
boolean
Description
当 by_parts 或 by_color 请求的 prompt 未指定任何部件名称时，此值为 true，表示 Meshy 转而自动拆分了模型——结果中的部件名称是 Meshy 生成的，而不是你提供的。从 PENDING 起就会出现该字段。对于 auto 任务，以及任何遵循了提示词的情况，此字段会被省略。
Name
part_count
Type
integer
Description
拆分产生的可打印部件数量。支持 scene 对象的格式会为每个部件携带一个对象；stl 会将它们熔合为一个整体，但计数仍报告部件数量。分割过程中无法生成可打印部件的坍缩薄片，会在导出前从文件中移除，且不计入计数。
Name
progress
Type
integer
Description
任务的进度。如果任务尚未开始，此属性值为 0。任务成功后，此值将变为 100。
Name
status
Type
string
Description
任务的状态。可能的值为 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
preceding_tasks
Type
integer
Description
排在此任务之前的任务数量。
此字段的值仅在任务状态为 PENDING 时才有意义。
Name
created_at
Type
timestamp
Description
任务创建时间的时间戳，单位为毫秒。
Name
started_at
Type
timestamp
Description
任务开始时间的时间戳，单位为毫秒。如果任务尚未开始，此属性值为 0。
Name
finished_at
Type
timestamp
Description
任务完成时间的时间戳，单位为毫秒。如果任务尚未完成，此属性值为 0。
Name
task_error
Type
object
Description
失败任务的错误详情。完整的 task_error 对象参考请参见 Errors。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。始终存在：任务被接受后为 10，对于 FAILED 任务则为 0，因为失败时费用会被退还。在任务仍处于 PENDING 状态时删除它，也会退还费用。

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split API

创建 Auto Split 任务

参数

返回值

失败情形

Request

Response

获取 Auto Split 任务

参数

返回

Request

Response

删除一个 Auto Split 任务

路径参数

任务状态

返回值

Request

Response

获取 Auto Split 任务列表

参数

可选属性

返回值

Request

Response

流式获取 Auto Split 任务

参数

返回

Request

Response Stream

The Auto Split Task Object

The Auto Split Task Object