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.

Auto Split currently supports untextured models only. For Image to 3D and Multi-Image to 3D, generate the input with should_texture set to false. A textured input is rejected with 400.

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

  • 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.
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. Up to 600 characters. Two failure modes: a description that reads as a split but names fewer than two parts (for example split into individual 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. 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.

  • 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 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.

  • 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 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.
  • 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.cn/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.cn/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.cn/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.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",
  "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.

Returns

Returns 200 OK on success.

Request

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

Response

// Returns 200 Ok on success.
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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?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
  }
]
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, part_count and parts 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.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
}

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. Every part is a separate object in the file. 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
      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 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.

  • 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.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
}