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，而一旦任务进入 SUCCEEDED 状态，则会出现 model_urls、thumbnail_url 和 part_count。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
}

Auto Split 任务对象

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

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-sortable UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。此值为 print-split。
Name
model_urls
Type
object
Description
拆分后模型的可下载 URL，每种请求的格式各对应一个。支持场景对象的格式会将每个部件保留为单独的对象；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
拆分产生的可打印部件数量。支持场景对象的格式每个部件对应一个对象；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。如果模型提供方的安全检查拒绝了输入模型，任务将以 task_error.type 为 invalid_input、code 为 provider_content_refused 而失败。参阅 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

Create an Auto Split Task

参数

返回值

失败模式

Request

Response

获取 Auto Split 任务

参数

返回值

Request

Response

删除一个 Auto Split 任务

路径参数

任务状态

返回值

Request

Response

获取 Auto Split 任务列表

参数

可选属性

返回值

Request

Response

流式获取 Auto Split 任务

参数

返回

Request

Response Stream

Auto Split 任务对象

The Auto Split Task Object