Auto Split API

Split a 3D model into separately printable parts — automatically, by the parts you name, or by color region — with optional connectors; thin regions left by a cut are always reinforced so every part prints solid.

The split result does not preserve the input texture. Auto Split accepts textured inputs, so you do not need to regenerate the model with should_texture: false. It rebuilds the cut parts and assigns each one a flat vertex color; no input texture map is carried into any exported format.

POST/openapi/v1/print/split

Create an Auto Split Task

This endpoint creates a new Auto Split task. The task cuts the model of a previous task into separately printable parts and returns the segmented model, with every part as its own object in the file.

Parameters

Name
input_task_id
Type
string
Required
Description
The ID of a succeeded task whose model to split. Supported task types: Image to 3D, Multi-Image to 3D, Text to 3D (preview), Remesh, Convert, and Resize. The task must have a status of SUCCEEDED, and its model must be generated with Meshy 6 or Meshy 7 (ai_model meshy-6, meshy-7, meshy-7.1, or latest). Low-poly and Smart Topology (meshy-t2) models are not supported. A textured model is accepted, and its texture is not carried into the result.

Name
mode
Type
string
default auto
Description
How the model is divided into parts.
Available values:
- auto: Meshy chooses the cuts. prompt is ignored.
- by_parts: Cut along the structural parts you name in prompt, such as head, arms, and torso.
- by_color: Cut along the color regions you name in prompt. Requires an input generated from an uploaded image (Image to 3D or Multi-Image to 3D); other inputs are rejected with 400. The color-region boundaries come from the source image, not from the input model's texture. For Multi-Image to 3D, Auto Split uses the first source image.

Applies only when mode = by_parts or by_color

Name
prompt
Type
string
Required
Description
Describes the parts to split into, in any language. Meshy reads 1 to 10 part names from it, so name the pieces rather than describing the model — for example split into the figure and the base, or head, torso, left arm, right arm, legs. Naming a single part is fine: everything you did not name becomes one remaining part, so the head splits the model into the head and the rest, as in the web app. Up to 600 characters. Two failure modes: a description that asks for no split at all, or names more than 10 parts, is rejected with 400 and nothing is charged; a description Meshy cannot read at all falls back to auto, the task still runs and is charged, and its response carries prompt_ignored: true.

Name
target_formats
Type
array
default ["glb"]
Description
Formats to export the split model in. Formats that support scene objects (glb, obj, fbx, usdz, blend, 3mf) carry each part as a separate object; stl has no notion of separate objects, so it fuses every part into one solid arranged by layout (request 3mf for separately selectable parts in a slicer). glb is always produced and returned in model_urls; list any other formats you want in addition.
Available values: glb, obj, fbx, stl, usdz, blend, 3mf.
Name
layout
Type
string
default assembled
Description
How the parts are arranged in every output format, and in the thumbnail.
Available values:
- assembled: Parts stay where the source model had them.
- on_plate: Parts are laid flat and spread out on the build plate, ready to slice — the same arrangement as the web app's On Plate view.
In both layouts a collapsed sliver or point-like piece left over from a cut is removed before export, so every part you get is printable. Formats that support scene objects hold one object per part; stl fuses them into a single solid.
Name
connectors
Type
boolean
default false
Description
Adds mortise-and-tenon connectors at each cut so the printed parts fit together.

Applies only when connectors = true

Name
connector_type
Type
string
default cube
Description
The shape of the connector at each cut surface.
Available values: cube, cylinder.
Name
connector_size
Type
number
default 0.5
Description
Connector size relative to the cut surface.
Valid range: 0.1 to 0.8.
Name
connector_height
Type
number
default 0.1
Description
How far the connector extends from the cut surface, relative to the cut surface.
Valid range: 0.1 to 0.8.

Returns

The result property of the response contains the id of the newly created Auto Split task.

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing prompt: prompt is required when mode is by_parts or by_color.
- Prompt describes no split, or too many parts: by_parts / by_color accepts 1 to 10 named pieces. A description that asks to keep the model in one piece, or names more than 10 parts, is rejected. Nothing is charged.
- Unsupported input task: The input_task_id must refer to a succeeded task of a supported type, generated with Meshy 6 or Meshy 7.
- No reference image: by_color requires an input generated from an uploaded image.
- Out-of-range connector: connector_size or connector_height is outside 0.1 to 0.8.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
404 - Not Found
Description
The input_task_id does not exist or does not belong to your account.
Name
429 - Too Many Requests
Description
You have exceeded your rate limit. by_parts and by_color requests also share a prompt-parsing limit of 12 requests per minute per account.
Name
503 - Service Unavailable
Description
Prompt-based splitting (by_parts and by_color) is temporarily unavailable. Retry later, or use mode: "auto", which is unaffected. Nothing is charged.

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, 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",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

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

Retrieve an Auto Split Task

This endpoint retrieves an Auto Split task by its ID.

Parameters

Name
id
Type
path
Description
The ID of the Auto Split task to retrieve.

Returns

The Auto Split Task object.

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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

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

Delete an Auto Split Task

This endpoint permanently deletes an Auto Split task, including all associated models and data. This action is irreversible.

Path Parameters

Name
id
Type
path
Description
The ID of the Auto Split task to delete.

Task Status

A task that is still PENDING is deleted and the credits consumed at create-time are refunded.

A task that is already IN_PROGRESS cannot be deleted: the request is rejected with 409 Conflict and the task keeps running. Credits for a task the worker has already started are not refundable, so deleting it mid-run would cost you the credits and the result both. Wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it.

A task in a terminal state (SUCCEEDED, FAILED or CANCELED) is deleted without a refund.

Returns

Returns 200 OK on success, or 409 Conflict when the task is IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/print/split

List Auto Split Tasks

This endpoint allows you to retrieve a list of Auto Split tasks.

Parameters

Optional attributes

Name
page_num
Type
integer
Description
Page number for pagination. Starts and defaults to 1.
Name
page_size
Type
integer
Description
Page size limit. Defaults to 10 items. Maximum allowed is 100 items; larger values are clamped to 100.
Name
sort_by
Type
string
Description
Field to sort by. Available values:
- +created_at: Sort by creation time in ascending order.
- -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of The Auto Split Task Objects.

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
  }
]

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

Stream an Auto Split Task

This endpoint streams real-time updates for an Auto Split task using Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unique identifier for the Auto Split task to stream.

Returns

Returns a stream of The Auto Split Task Objects as Server-Sent Events.

Every message event carries the full task object as returned by Retrieve an Auto Split Task, including consumed_credits, the timestamps and prompt_ignored; while the task is PENDING or IN_PROGRESS the fields that change between frames are progress, status, started_at and preceding_tasks, and model_urls, thumbnail_url and part_count appear once it reaches SUCCEEDED. An error event carries only status_code and message, so branch on the event name before reading 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

An Auto Split task carries only the properties below. The generation-prompt fields other task objects include (name, object_prompt, texture_prompt and so on), the single model_url, and texture_urls are never populated for a split and are not returned. Properties that fill in as the task runs (thumbnail_url, model_urls, the timestamps) are always present, empty until they have a value, so the set of keys does not change between PENDING and SUCCEEDED.

Name
id
Type
string
Description
Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.
Name
type
Type
string
Description
Type of the task. The value is print-split.
Name
model_urls
Type
object
Description
Downloadable URLs to the split model, one per requested format. Formats that support scene objects keep each part as a separate object; stl fuses them into one solid. The property for a format will be omitted if the format was not requested.
- Name
  glb
  Type
  string
  Description
  Downloadable URL to the split model in GLB format.
- Name
  obj
  Type
  string
  Description
  Downloadable URL to the split model in OBJ format.
- Name
  fbx
  Type
  string
  Description
  Downloadable URL to the split model in FBX format.
- Name
  stl
  Type
  string
  Description
  Downloadable URL to the split model in STL format. All parts are fused into one solid; request 3mf for separately selectable parts.
- Name
  usdz
  Type
  string
  Description
  Downloadable URL to the split model in USDZ format.
- Name
  blend
  Type
  string
  Description
  Downloadable URL to the split model in Blender format.
- Name
  3mf
  Type
  string
  Description
  Downloadable URL to the split model in 3MF format.
Name
thumbnail_url
Type
string
Description
Downloadable URL to a rendered preview of the split model, with each part in a distinct color, in the requested layout.
Name
prompt_ignored
Type
boolean
Description
true when a by_parts or by_color request's prompt named no parts, so Meshy split the model automatically instead — the part names in the result are Meshy's, not yours. Present from PENDING on. Omitted for auto tasks and whenever the prompt was followed.
Name
part_count
Type
integer
Description
Number of printable parts the split produced. Formats that support scene objects carry one object per part; stl fuses them into one solid, and the count still reports the parts. Collapsed slivers that the segmentation could not turn into a printable piece are removed from the files before export and are not counted.
Name
progress
Type
integer
Description
Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks.
The value of this field is meaningful only if the task status is PENDING.
Name
created_at
Type
timestamp
Description
Timestamp of when the task was created, in milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.
Name
task_error
Type
object
Description
Error details for failed tasks. See Errors for the full task_error object reference.
Name
consumed_credits
Type
integer
Description
The number of credits consumed by this task. Always present: 10 once the task has been accepted, and 0 for FAILED tasks because the charge is refunded on failure. Deleting a task while it is still PENDING also refunds it.

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
}