Auto Split API

将 3D 模型拆分为可分别打印的多个部件。Meshy 会自行选择切割位置，或沿着你指定的部件或颜色区域进行切割，并可以添加连接件。Meshy 始终会对切割后留下的薄弱区域进行加固，以确保每个部件都能牢固地打印出来。

默认情况下，拆分后的模型不会保留输入模型的texture。 你可以拆分一个带有texture的模型，因此无需使用 should_texture: false 重新生成它。Meshy 会重建切割后的部件，并为每个部件赋予纯色顶点颜色。若要在每个部件上保留texture，请发送 keep_texture: true。

POST/openapi/v1/print/split

创建一个 Auto Split 任务

创建一个 Auto Split 任务。该任务会将先前任务的模型切割成可以分别打印的多个部件。它返回切割后的模型，文件中每个部件都作为独立对象存在。

该任务在后台运行。关于任务通常需要多长时间，请参阅处理时间。

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, keep the texture, add connectors, export glb and obj
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "keep_texture": true,
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

参数

Name
input_task_id
Type
string
必选
Description
要切割其模型的任务的 ID。该任务的状态必须为 SUCCEEDED。以下任务类型可用：
- Image to 3D
- Multi-Image to 3D
- Text to 3D，preview 或 refine 任务
- Retexture
- Remesh
- Convert
- Resize
模型必须由 Meshy 6 或 Meshy 7 生成，即 ai_model 设置为 meshy-6-lite、meshy-6、meshy-7、meshy-7.1 或 latest。不支持 Smart Topology 模型（meshy-t2 和 meshy-t2.5）。对于 refine、Retexture、Remesh、Convert 或 Resize 任务，该规则适用于任务最初所基于的模型。由上传模型创建的 Retexture、Remesh、Convert 或 Resize 任务会返回 400。
模型面数最多为 8,000,000。面数更多的模型会返回 400。在这种情况下，请先对其运行 Remesh 任务，然后改为发送该 Remesh 任务的 ID。
你可以切割带贴图的模型。要在各部件上保留其贴图，请发送 keep_texture: true。

Name
mode
Type
string
默认值 auto
Description
如何将模型划分为多个部件。
可用值：
- auto：由 Meshy 选择切割方式，并忽略 prompt。即使 prompt 超过 600 个字符，仍会返回 400。
- by_parts：Meshy 按你在 prompt 中指定的结构部件进行切割，例如头部、手臂和躯干。
- by_color：Meshy 按你在 prompt 中指定的颜色区域进行切割。Meshy 会在源图像中查找这些区域，而不是在输入模型的贴图中查找。输入模型必须是通过 Image to 3D 或 Multi-Image to 3D 从上传的图像生成的。其他输入会返回 400。对于 Multi-Image to 3D，Meshy 会使用第一张源图像。

仅当 mode = by_parts or by_color

Name
prompt
Type
string
必选
Description
要将模型拆分成的各个部件，可使用任意语言，最多 600 个字符。更长的文本会返回 400，即使 mode 为 auto 时也是如此。
Meshy 会从 prompt 中读取 1 到 10 个部件名称，因此请直接命名各部件，而不要描述模型。例如，split into the figure and the base 或 head, torso, left arm, right arm, legs。你可以只命名单个部件。所有未命名的部分会合并成另外一个部件，因此 the head 会将模型拆分为头部和其余部分，与 Web App 中的行为一致。
要求不进行拆分，或命名超过 10 个部件的 prompt 会返回 400，且 Meshy 不会就此请求扣费。
如果 Meshy 无法从 prompt 中读取到任何部件名称，它会改用该模型的参考图像。它会按你选择的 mode，沿着在该图像中找到的部件进行切割。此时任务仍会运行，Meshy 仍会扣费，且该任务的 prompt_ignored 为 true。如果模型没有参考图像，或 Meshy 在其中找到的部件少于 2 个，请求将返回 400，且 Meshy 不会就此请求扣费。

Name
target_formats
Type
array
默认值 ["glb"]
Description
要生成的文件格式。Meshy 始终生成 glb 并在 model_urls 中返回它，再加上你列出的其他格式。
可用值：
- glb
- obj
- fbx
- stl
- usdz
- blend
- 3mf
除 stl 外，每种格式都支持 scene 对象，并将每个部件保存为单独的对象。STL 文件不能保存独立对象，因此 Meshy 会将这些部件融合为一个实体，按 layout 排列。要获得可以在 slicer 中分别选中的部件，请请求 3mf。
设置 keep_texture: true 时，以下格式会保留贴图：
- glb、fbx、usdz 和 blend：贴图包含在文件中。
- obj：贴图包含在 material 文件中，model_urls 会在 mtl 下返回该文件。
- stl 和 3mf：文件仅保存 geometry，不包含贴图。
Name
layout
Type
string
默认值 assembled
Description
Meshy 在每种文件格式以及 thumbnail 中排列各部件的方式。
可用值：
- assembled：Meshy 保持各部件在源模型中的原有位置。
- on_plate：Meshy 将各部件平铺并在构建板上展开排列，便于直接切片。这与 Web App 中的 On Plate 视图排列方式相同。
在这两种 layout 下，Meshy 都会在导出前移除切割产生的任何已坍缩的碎片或点状碎片，因此你得到的每个部件都是可打印的。支持 scene 对象的格式会为每个部件保存一个对象，而 stl 会将各部件融合为一个实体。
Name
keep_texture
Type
boolean
默认值 false
Description
是否在各部件上保留输入模型的贴图。true 会让每个部件都带有输入模型的贴图，任务会在 texture_urls 中返回这些贴图。false 则会让每个部件呈现单一的顶点颜色。
设置为 true 时，任务耗时约为原来的两倍，积分消耗不变。未贴图的输入模型，无论设置为 true 还是 false，其拆分方式相同。如果 Meshy 无法保留贴图，任务会以错误代码 textured_split_refused 失败。请参阅Errors。
Name
connectors
Type
boolean
默认值 false
Description
是否在每个切割处添加榫卯连接件，以便打印出的各部件能够拼接在一起。

仅当 connectors = true

Name
connector_type
Type
string
默认值 cube
Description
连接件在每个切割面上的形状，cube 或 cylinder。
Name
connector_size
Type
number
默认值 0.5
Description
连接件相对于切割面的大小，范围为 0.1 到 0.8。超出此范围的值会返回 400，即使 connectors 为 false 时也是如此。
Name
connector_height
Type
number
默认值 0.1
Description
连接件相对于切割面凸出的程度，范围为 0.1 到 0.8。超出此范围的值会返回 400，即使 connectors 为 false 时也是如此。

返回值

响应的 result 字段保存新 Auto Split 任务的 ID。

失败情形

Name
400 - Bad Request
Description
请求无法运行。错误消息会说明发现的问题。例如：
- Missing prompt：mode 为 by_parts 或 by_color，但缺少 prompt。
- Prompt describes no split, or too many parts：prompt 要求保持模型为一个整体，或命名了超过 10 个部件。by_parts 和 by_color 接受 1 到 10 个指定名称的部件。Meshy 不会就此请求扣费。
- Unsupported input task：input_task_id 不是受支持类型的成功任务，或并非由 Meshy 6 或 Meshy 7 生成。
- No reference image：mode 为 by_color，但输入模型并非由上传的图像生成。
- Out-of-range connector：connector_size 或 connector_height 超出 0.1 到 0.8 的范围。
修正请求后重新发送。请参阅Errors。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- Insufficient credits：账户没有足够的积分来执行此任务，或账户已达到积分限额。请检查你的积分 balance，然后重试。
- Free plan：创建任务需要付费方案。请在subscription 设置中升级你的方案，然后重试。
Name
403 - Forbidden
Description
以下情形之一：
- 内容审核（moderation）拦截了该 prompt。消息为 explicit content 或 prohibited content。修改 prompt 后重试。
- input_task_id 是一个浮雕模型，该 endpoint 无法对其进行拆分。消息为 This model type does not support this operation。请发送其他模型。
Name
404 - Not Found
Description
input_task_id 不存在，或不属于你的账户。请检查该 ID，并使用创建该任务的账户对应的 API key。
Name
429 - Too Many Requests
Description
你已超出速率限制。请稍候后重试。请参阅Rate limits。
by_parts 和 by_color 请求还共享一个每个账户每分钟 12 次请求的 prompt 读取限制。
Name
503 - Service Unavailable
Description
按 prompt 拆分（by_parts 和 by_color）暂时不可用。请稍后重试，或发送 mode: "auto"，该模式仍可正常使用。Meshy 不会就此请求扣费。

GET/openapi/v1/print/split/:id

获取 Auto Split 任务

根据任务 ID 返回对应的 Auto Split 任务。

Request

GET

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

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

Response

{
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_metallic.png?Expires=***",
      "normal": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_normal.png?Expires=***",
      "roughness": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_roughness.png?Expires=***"
    }
  ],
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

Auto Split 任务对象。

DELETE/openapi/v1/print/split/:id

删除 Auto Split 任务

永久删除一个 Auto Split 任务，包括其模型和数据。删除操作无法撤销。

Request

DELETE

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

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

路径参数

Name
id
Type
path
Description
要删除的任务的 ID。

任务状态

删除处于 PENDING 状态的任务，会退还你创建该任务时所使用的积分。

处于 IN_PROGRESS 状态的任务无法被删除。该请求会返回 409 Conflict，任务会继续运行。Meshy 不会为已经开始的任务退款，因此删除它会让你同时损失积分和结果。请等待任务进入 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

删除处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务不会退还其积分。

返回值

任务被删除时返回 200 OK；当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

GET/openapi/v1/print/split

列出 Auto Split 任务

返回你的 Auto Split 任务列表。

Request

GET

/openapi/v1/print/split

curl https://api.meshy.ai/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "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=***"
    },
    "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
  }
]

参数

Name
page_num
Type
integer
Description
要返回的页码。从 1 开始，默认为 1。
Name
page_size
Type
integer
Description
每页返回的任务数量，最多为 100。默认为 10。Meshy 会将更大的值按 100 处理。
Name
sort_by
Type
string
Description
排序方式。
可用值：
- +created_at：最早的在前
- -created_at：最新的在前

一个分页的 Auto Split 任务对象列表。

GET/openapi/v1/print/split/:id/stream

流式获取 Auto Split 任务

以服务器发送事件（SSE）的形式流式传输 Auto Split 任务的更新。

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
}

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

以服务器发送事件形式返回的 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 之前请先检查事件名称。

Auto Split 任务对象

Auto Split 任务对象描述了一次 3D 模型的拆分。它保存了任务成功时的状态、progress 和部件文件。

它不包含其他任务对象的 prompt 字段，例如 name、object_prompt 和 texture_prompt。它也没有单一的 model_url。thumbnail_url、model_urls 以及时间戳会随着任务运行而被填入。它们始终存在，在有值之前为空。

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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_metallic.png?Expires=***",
      "normal": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_normal.png?Expires=***",
      "roughness": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_roughness.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
}

Name
id
Type
string
Description
任务 ID。请将其视为不透明字符串，不要依赖其格式。
Name
type
Type
string
Description
任务类型，始终为 print-split。
Name
model_urls
Type
object
Description
拆分模型的下载 URL，每个你请求的格式对应一个。你未请求的格式不会出现对应的键。支持 scene 对象的格式会将每个部件保留为单独的对象，而 stl 会将所有部件融合成一个实体。
- Name
  glb
  Type
  string
  Description
  GLB 文件。
- Name
  obj
  Type
  string
  Description
  OBJ 文件。
- Name
  mtl
  Type
  string
  Description
  MTL 文件。当 keep_texture 为 true 且输入模型带有 texture 时，会随 OBJ 文件一同出现。
- Name
  fbx
  Type
  string
  Description
  FBX 文件。
- Name
  stl
  Type
  string
  Description
  STL 文件，所有部件会融合成一个实体。如果需要可单独选择的部件，请请求 3mf。
- Name
  usdz
  Type
  string
  Description
  USDZ 文件。
- Name
  blend
  Type
  string
  Description
  Blender 文件。
- Name
  3mf
  Type
  string
  Description
  3MF 文件。
Name
thumbnail_url
Type
string
Description
拆分模型预览图的下载 URL，使用你请求的 layout。当部件保留 texture 时，预览图会展示该 texture；否则，每个部件会有各自的颜色。
Name
texture_urls
Type
array
Description
拆分模型的 texture 贴图，是一个包含一个对象的数组。所有部件共享这些贴图。仅当 keep_texture 为 true 且输入模型带有 texture 时才会出现。
- Name
  base_color
  Type
  string
  Description
  基础颜色贴图的下载 URL。
- Name
  metallic
  Type
  string
  Description
  金属度贴图的下载 URL。当输入没有金属度贴图时不存在。
- Name
  normal
  Type
  string
  Description
  法线贴图的下载 URL。当输入没有法线贴图时不存在。
- Name
  roughness
  Type
  string
  Description
  粗糙度贴图的下载 URL。当输入没有粗糙度贴图时不存在。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景版本（RGBA）的下载 URL。仅在任务成功后，且 Meshy 渲染了透明预览图时才会出现。
Name
prompt_ignored
Type
boolean
Description
Meshy 是否忽略了该 prompt。当 by_parts 或 by_color 请求中的 prompt 未指定任何部件名称时，该值为 true，此时 Meshy 会自动拆分模型。结果中的部件名称随之由 Meshy 命名，而非你指定的名称。从 PENDING 状态起出现。对于 auto 任务，以及任何 Meshy 按 prompt 执行的情况，该字段会被省略。
Name
part_count
Type
integer
Description
拆分生成的可打印部件数量。支持 scene 对象的格式中，每个部件对应一个对象。stl 会将部件融合成一个实体，但 part_count 仍会计入它们的数量。在导出之前，Meshy 会移除无法成为可打印部件的塌陷碎片，且不计入这些碎片。
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
任务创建的时间，以 Unix 毫秒表示。
Name
started_at
Type
timestamp
Description
任务开始的时间，以 Unix 毫秒表示。在任务开始之前为 0。
Name
finished_at
Type
timestamp
Description
任务完成的时间，以 Unix 毫秒表示。在任务完成之前为 0。
Name
expires_at
Type
timestamp
Description
任务结果过期的时间，以 Unix 毫秒表示。在任务完成之前为 0。
Name
task_error
Type
object
Description
任务失败时的错误详情。请参阅 Errors。
如果安全检查拒绝了输入模型，任务会失败，task_error.type 被设为 invalid_input，task_error.code 被设为 provider_content_refused。请发送其他模型。请参阅 Errors。
在 keep_texture: true 的情况下，如果 Meshy 无法保留 texture，任务会失败，task_error.code 被设为 textured_split_refused。请参阅 Errors。
Name
consumed_credits
Type
integer
Description
任务消耗的积分数量。该字段始终存在。Meshy 接受任务后该值为 10，FAILED 任务的值为 0，因为任务失败时 Meshy 会退还积分。删除 PENDING 任务同样会退还积分。