Auto Split API

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

Auto Split 目前仅支持未贴图的模型。对于 Image to 3D 和 Multi-Image to 3D，请在生成输入时将 should_texture 设置为 false。带贴图的输入将返回 400 错误并被拒绝。对贴图模型的支持正在开发中。

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 和 parts 会在任务到达 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
}

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-可排序的 UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。此值为 print-split。
Name
model_urls
Type
object
Description
拆分模型的可下载 URL，每个请求的格式对应一个。文件中每个部件都是一个独立的对象。如果未请求某种格式，则对应该格式的属性将被省略。
- Name
  glb
  Type
  string
  Description
  GLB 格式拆分模型的可下载 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 格式拆分模型的可下载 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 格式拆分模型的可下载 URL。
- Name
  usdz
  Type
  string
  Description
  USDZ 格式拆分模型的可下载 URL。
- Name
  blend
  Type
  string
  Description
  Blender 格式拆分模型的可下载 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 格式拆分模型的可下载 URL：每个部件对应一个对象，每个对象都位于自己的耗材槽位上，单位为毫米，缩放比例使最长边为 150 毫米，并带有 Bambu Studio 项目配置。
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
拆分模型中可打印部件的数量 —— 每个导出文件中的对象对应一个部件。分割过程中无法转换为可打印部件的坍缩碎片，会在导出前从文件中移除，不计入此数量。
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

List Auto Split Tasks

参数

可选属性

返回值

Request

Response

流式获取 Auto Split 任务

参数

返回值

Request

Response Stream

Auto Split 任务对象

The Auto Split Task Object