Auto Split API

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, or latest). Low-poly and Smart Topology (meshy-t2) models are not supported.

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.

Formats to export the split model in. Each part is a separate object in every format. glb is always produced and returned in model_urls; list any other formats you want in addition.

Available values: glb, obj, fbx, usdz, blend, 3mf.

3mf is written for slicers: one object per part, each on its own filament slot, so Bambu Studio opens the file as individually coloured, separately selectable parts (the archive carries a Bambu Studio project configuration; other slicers read the geometry). Like Meshy's other print formats it is in millimetres and, because this endpoint takes no target size, the whole model is scaled so its longest side is 150 mm — the same cap the other print-format exports use, chosen to fit every mainstream build plate. With layout: "on_plate" the cap applies to the laid-out plate as a whole, so the file is ready to slice; with assembled, the parts sit where the source model had them and you arrange them in the slicer.

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 the exported files hold one object per part and nothing else: a collapsed sliver or point-like piece left over from a cut is removed before export, so every object you find in the file is printable.

Adds mortise-and-tenon connectors at each cut so the printed parts fit together.

The request was unacceptable. Common causes:

• Missing prompt: prompt is required when mode is by_parts or by_color.
• Prompt names fewer than two parts: by_parts / by_color needs at least two named pieces (for example head, torso, base); a generic instruction such as split into individual 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.
• Textured input: The input model has textures. Only untextured models are supported for now.
• No reference image: by_color requires an input generated from an uploaded image.
• Unsupported format: target_formats contains stl.
• Out-of-range connector: connector_size or connector_height is outside 0.1 to 0.8.

Authentication failed. Please check your API key.

Insufficient credits to perform this task.

The input_task_id does not exist or does not belong to your account.

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.

Prompt-based splitting (by_parts and by_color) is temporarily unavailable. Retry later, or use mode: "auto", which is unaffected. Nothing is charged.

The ID of the Auto Split task to retrieve.

The ID of the Auto Split task to delete.

Page number for pagination. Starts and defaults to 1.

Page size limit. Defaults to 10 items. Maximum allowed is 100 items; larger values are clamped to 100.

Field to sort by. Available values:

• +created_at: Sort by creation time in ascending order.
• -created_at: Sort by creation time in descending order.

Unique identifier for the Auto Split task to stream.

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.

Type of the task. The value is print-split.

Downloadable URLs to the split model, one per requested format. Every part is a separate object in the file. The property for a format will be omitted if the format was not requested.

Downloadable URL to a rendered preview of the split model, with each part in a distinct color, in the requested layout.

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.

Number of printable parts in the split model — one per object in the exported files. Collapsed slivers that the segmentation could not turn into a printable piece are removed from the files before export and are not counted.

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.

Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

The count of preceding tasks.

Timestamp of when the task was created, in milliseconds.

Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.

Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.

Error details for failed tasks. See Errors for the full task_error object reference.

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.