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.cn/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.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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，每种请求的格式对应一个。文件中的每个部件都是一个独立的对象。如果未请求某种格式，则该格式对应的属性将被省略。
- 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。
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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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