Auto Split API

The ID of the task whose model to split. The task must have the status SUCCEEDED. These task types work:

• Image to 3D
• Multi-Image to 3D
• Text to 3D, a preview or refine task
• Retexture
• Remesh
• Convert
• Resize

The model must be generated with Meshy 6 or Meshy 7, that is, with ai_model set to meshy-6-lite, meshy-6, meshy-7, meshy-7.1, or latest. Smart Topology models (meshy-t2 and meshy-t2.5) aren't supported. For a refine, Retexture, Remesh, Convert, or Resize task, the rule applies to the model the task started from. A Retexture, Remesh, Convert, or Resize task made from an uploaded model returns 400.

The model can have at most 8,000,000 faces. A model with more faces returns 400. In that case, run a Remesh task on it first, and send the Remesh task's ID instead.

You can split a textured model. To keep its texture on the parts, send keep_texture: true.

How to divide the model into parts.

Available values:

• auto: Meshy chooses the cuts and ignores prompt. A prompt over 600 characters still returns 400.
• by_parts: Meshy cuts along the structural parts you name in prompt, for example head, arms, and torso.
• by_color: Meshy cuts along the color regions you name in prompt. Meshy finds the regions in the source image, not in the input model's texture. The input must be generated from an uploaded image, with Image to 3D or Multi-Image to 3D. Other inputs return 400. For Multi-Image to 3D, Meshy uses the first source image.

The file formats to generate. Meshy always generates glb and returns it in model_urls, plus the other formats you list.

Available values:

• glb
• obj
• fbx
• stl
• usdz
• blend
• 3mf

Every format except stl supports scene objects and holds each part as a separate object. An STL file can't hold separate objects, so Meshy fuses the parts into one solid, arranged by layout. To get parts you can select separately in a slicer, request 3mf.

With keep_texture: true, these formats hold the texture:

• glb, fbx, usdz, and blend: The texture is in the file.
• obj: The texture is in the material file, which model_urls returns under mtl.
• stl and 3mf: The file holds geometry only, without the texture.

How Meshy arranges the parts, in every file format and in the thumbnail.

Available values:

• assembled: Meshy keeps the parts where they were in the source model.
• on_plate: Meshy lays the parts flat and spreads them out on the build plate, ready to slice. This is the same arrangement as the On Plate view in the web app.

In both layouts, Meshy removes any collapsed sliver or point-like piece a cut leaves before export, so every part you get is printable. Formats that support scene objects hold one object per part, and stl fuses the parts into one solid.

Whether to keep the input model's texture on the parts. true gives every part the input's texture, and the task returns the maps in texture_urls. false gives each part a flat vertex color.

With true, the task takes about twice as long, and the credit cost doesn't change. An untextured input splits the same way as with false. If Meshy can't keep the texture, the task fails with the error code textured_split_refused. See Errors.

Whether to add mortise-and-tenon connectors at each cut, so the printed parts fit together.

The request can't run. The error message says which problem it found. For example:

• Missing prompt: mode is by_parts or by_color, and prompt is missing.
• Prompt describes no split, or too many parts: The prompt asks to keep the model in one piece, or names more than 10 parts. by_parts and by_color accept 1 to 10 named parts. Meshy doesn't charge for the request.
• Unsupported input task: input_task_id isn't a succeeded task of a supported type, generated with Meshy 6 or Meshy 7.
• No reference image: mode is by_color, and the input wasn't generated from an uploaded image.
• Out-of-range connector: connector_size or connector_height is outside 0.1 to 0.8.

Fix the request, then send it again. See Errors.

The API key is missing or invalid. Check the Authorization header.

For example:

• Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. Check your credit balance, then retry.
• Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.

One of these applies:

• Content moderation blocked the prompt. The message is explicit content or prohibited content. Change the prompt, then retry.
• input_task_id is a bas-relief model, which this endpoint can't split. The message is This model type does not support this operation. Send a different model.

input_task_id doesn't exist or doesn't belong to your account. Check the ID, and use an API key from the account that created the task.

You exceeded your rate limit. Wait, then retry. See Rate limits.

by_parts and by_color requests also share a prompt-reading limit of 12 requests per minute per account.

Splitting by prompt (by_parts and by_color) is temporarily unavailable. Retry later, or send mode: "auto", which still works. Meshy doesn't charge for the request.

The task ID from the create response.

The ID of the task to delete.

The page number to return. Starts at and defaults to 1.

The number of tasks per page, up to 100. Defaults to 10. Meshy treats a larger value as 100.

The sort order.

Available values:

• +created_at: oldest first
• -created_at: newest first

The task ID from the create response.

The task ID. Treat it as an opaque string, and don't rely on its format.

The task type, always print-split.

Download URLs for the split model, one per format you requested. A format you didn't request has no key. Formats that support scene objects keep each part as a separate object, and stl fuses the parts into one solid.

Download URL for a preview image of the split model, in the layout you requested. When the parts keep a texture, the preview shows it. Otherwise, each part has its own color.

The texture maps of the split model, as an array with one object. All parts share these maps. Present only when keep_texture is true and the input model is textured.

Download URL for a version of thumbnail_url with a transparent background (RGBA). Present only after the task succeeds, when Meshy rendered the transparent preview.

Whether Meshy ignored the prompt. It's true when the prompt of a by_parts or by_color request named no parts, so Meshy split the model automatically instead. The part names in the result are then Meshy's, not yours. Present from PENDING on. Meshy leaves it out for auto tasks and whenever it followed the prompt.

The number of printable parts the split produced. Formats that support scene objects hold one object per part. stl fuses the parts into one solid, but part_count still counts them. Before export, Meshy removes collapsed slivers that can't become a printable part, and doesn't count them.

How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.

The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.

The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING.

Time the task was created, in Unix milliseconds.

Time the task started, in Unix milliseconds. It's 0 until the task starts.

Time the task finished, in Unix milliseconds. It's 0 until the task finishes.

Time the task's result expires, in Unix milliseconds. It's 0 until the task finishes.

The error details when the task fails. See Errors.

If a safety check declines the input model, the task fails with task_error.type set to invalid_input and task_error.code set to provider_content_refused. Send a different model. See Errors.

With keep_texture: true, if Meshy can't keep the texture, the task fails with task_error.code set to textured_split_refused. See Errors.

The number of credits the task used. It's always present. It's 10 after Meshy accepts the task, and 0 for a FAILED task, because Meshy refunds the credits when a task fails. Deleting a PENDING task also refunds it.