Analyze Printability API

Analyze a 3D model for printability — watertightness, volume, holes, non-manifold edges, and degenerate faces. Optionally, also check wall thickness at the size you plan to print.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

This endpoint creates a new analyze-printability task. The task evaluates a 3D model and reports its printability metrics.

The task runs in the background. For how long it usually takes, see Processing Times.

If the input task already has cached printability, the returned task is immediately ready and the first GET on it will return the analysis result without going through the worker.

To also check wall thickness at the size you plan to print, send printer_type, a print size, or both. The result is returned in printability.thin_walls. Checking wall thickness takes longer, so the task is usually not ready right away, even if the model was analyzed before.

Parameters

Only one of input_task_id or model_url is required. If both are provided, input_task_id takes priority.

Name
input_task_id
Type
string
Required
Description
The ID of a succeeded task you own. Supported task types: Image to 3D, Multi-Image to 3D, Text to 3D, Remesh, and Retexture. The task must use Meshy 6 or newer (including Meshy 7) and must have a status of SUCCEEDED. Repair Printability tasks are also accepted.

Name
model_url
Type
string
Required
Description
URL of a 3D model to analyze. Supported formats: .glb, .gltf, .obj, .fbx, .stl. Maximum file size: 100 MB. Must use http, https, or a data: URL (data URLs bypass extension checks).
Meshy download URLs (assets.meshy.ai/…?Expires=…&Signature=…) are signed and stop working at the task's expires_at; fetching the task again does not renew them. For a model generated with Meshy, pass input_task_id instead. It works while the source task is retained (see Asset Retention). To reuse a model after that, download it before expires_at and send your own copy.

Send at most one of the two print size fields. If you send printer_type without a size, the default size is:

.glb and any input_task_id: 150 mm tall.
.stl: the file's own longest side, read as millimeters. For an STL in other units, send intended_print_longest_side_mm.
.obj, .fbx, .gltf: 150 mm on the longest side.

Name
printer_type
Type
string
Description
The printer you plan to use. It sets the minimum wall thickness for the wall-thickness check. Defaults to fdm when you send a print size without it.
Available values:
- fdm: filament, 1.0 mm minimum wall.
- sla: resin, 0.8 mm minimum wall.
- full_color: full-color, 2.0 mm minimum wall.
Name
intended_print_height_mm
Type
number
Description
Height of the print, in millimeters. Range: [1, 1000]. Rounded to the nearest millimeter. GLB input only.
Name
intended_print_longest_side_mm
Type
number
Description
Length of the print's longest side, in millimeters. Range: [1, 1000]. Rounded to the nearest millimeter. Works with every input format.

Returns

The result property of the response contains the id of the newly created analyze-printability task.

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing parameter: neither input_task_id nor model_url was provided.
- Invalid UUID: input_task_id is not a valid UUID.
- Invalid model URL: model_url is malformed, uses an unsupported scheme, or has an unsupported file extension.
- Model file too large: model_url body exceeded 100 MB.
- Model file could not be downloaded: model_url returned an error, most often because a signed Meshy download URL has expired. Fetching the task again returns the same URL with the same expiry, so send your own copy of the file, or use input_task_id while the source task is still retained.
- Task not succeeded: the referenced task is still pending, in progress, or failed.
- Invalid print size: intended_print_height_mm or intended_print_longest_side_mm is outside [1, 1000], or both were sent.
- Unknown printer type: printer_type is not fdm, sla, or full_color.
- Height on a non-GLB model: intended_print_height_mm was sent with a model_url that is not .glb. Use intended_print_longest_side_mm instead.
- Can't size this model by height: at the requested height (or the default 150 mm), the model's longest side would be outside [1, 1000] mm, the model is flat, or its size can't be determined. Use intended_print_longest_side_mm instead. For a .glb model_url and some input_task_id tasks, this is only found after the task starts, and the task ends FAILED instead.
- STL size unusable: printer_type was sent without a size, and the .stl's own longest side can't be read or is outside [1, 1000] mm. Send intended_print_longest_side_mm.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
403 - Forbidden
Description
The task exists but is owned by a different user.
Name
404 - Not Found
Description
Common causes:
- The task does not exist or has been deleted.
- The task uses a model older than Meshy 6, or its mode does not produce a 3D asset.
- The underlying model file is no longer available in storage.
Name
429 - Too Many Requests
Description
You have exceeded your pending-task quota or rate limit.

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

# Also check wall thickness for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

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

GET/openapi/v1/print/analyze/:id

Retrieve an Analyze Printability Task

This endpoint retrieves an analyze-printability task by its ID.

Parameters

Name
id
Type
path
Description
The ID of the analyze-printability task to retrieve.

Returns

The Analyze Printability Task Object. The printability field is null until the task reaches SUCCEEDED. When wall thickness was checked, printability also includes intended_print and thin_walls.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Delete an Analyze Printability Task

This endpoint permanently deletes an analyze-printability task and its cached result. This action is irreversible.

Path Parameters

Name
id
Type
path
Description
The ID of the analyze-printability 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/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/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/analyze

List Analyze Printability Tasks

This endpoint allows you to retrieve a list of analyze-printability 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.
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 Analyze Printability Task Objects.

Request

GET

/openapi/v1/print/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

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

Stream an Analyze Printability Task

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

Parameters

Name
id
Type
path
Description
Unique identifier for the analyze-printability task to stream.

Returns

Returns a stream of Analyze Printability Task Objects as Server-Sent Events.

Every frame carries the full task object for the stage — the same shape the Get endpoint returns — so while the task is PENDING or IN_PROGRESS the output fields are simply not populated yet (null, [] or {}) and finished_at is null. The printability block is sent only once the task reaches SUCCEEDED.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object

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 analyze-printability task. The value is print-analyze.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
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
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
expires_at
Type
timestamp
Description
Timestamp of when the task result will expire from the system, in milliseconds. 0 if the task has not yet finished.
Name
task_error
Type
object
Description
Error information if the task has failed. This property is null if the task has not failed. See Errors for more details.
- Name
  message
  Type
  string
  Description
  Error message describing what went wrong.
Name
printability
Type
object
Description
Printability evaluation result. null until the task reaches SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Schema version of the printability result. Currently v1.
- Name
  status
  Type
  string
  Description
  Overall status. One of:
  
  healthy: no errors and no warnings.
  
  warning: at least one warning, no errors.
  
  error: at least one error.
  
  unknown: the model could not be analyzed.
  
  When wall thickness was checked, this is the worse of the checks above and thin_walls.status. From worst to best: error, warning, unknown, healthy.
- Name
  issue_count
  Type
  integer
  Description
  Total count of issues, equal to error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Number of error-level issues. Errors are raised when the model is not watertight, has non-positive volume, or has non-manifold edges. When wall thickness was checked, walls that are too thin (thin_walls.status is error) count as one more error.
- Name
  warning_count
  Type
  integer
  Description
  Number of warning-level issues. Warnings are raised when the model contains degenerate faces or holes.
- Name
  metrics
  Type
  object
  Description
  Raw geometry metrics returned by the evaluator.
  Name
  is_watertight
  Type
  boolean
  Description
  true when the mesh has no boundary edges (i.e., is closed).
  Name
  volume
  Type
  number
  Description
  Volume of the model in cubic meters.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Count of non-manifold edges.
  Name
  degenerate_faces
  Type
  integer
  Description
  Count of degenerate faces (zero-area or invalid faces).
  Name
  holes
  Type
  integer
  Description
  Count of holes (boundary loops) in the mesh.
- Name
  intended_print
  Type
  object
  Description
  The printer and size the wall-thickness check used. Present only when wall thickness was checked.
  Name
  printer_type
  Type
  string
  Description
  fdm, sla, or full_color.
  Name
  height_mm
  Type
  number
  Description
  The print height in millimeters, if the print was sized by height. Otherwise null.
  Name
  longest_side_mm
  Type
  number
  Description
  The print's longest side in millimeters. When sized by height, it is calculated from the model's proportions.
  Name
  wall_thickness_mm
  Type
  number
  Description
  The minimum wall thickness for printer_type, in millimeters. Walls thinner than this are reported as too thin.
  Name
  dimensions_mm
  Type
  array
  Description
  The print's [width, depth, height] in millimeters. The height can differ from height_mm by a fraction of a millimeter. null for non-GLB input, or if the model's size can't be determined.
- Name
  thin_walls
  Type
  object
  Description
  The wall-thickness result. Present only when wall thickness was checked.
  Name
  thin_area_ratio
  Type
  number
  Description
  Share of the surface, from 0 to 1, that is thinner than intended_print.wall_thickness_mm. null if the model couldn't be measured.
  Name
  has_thin_walls
  Type
  boolean
  Description
  true if any part of the surface is too thin. Sharp corners alone can set this, so use status to decide whether the walls need thickening. null if the model couldn't be measured.
  Name
  status
  Type
  string
  Description
  The wall-thickness verdict. One of:
  
  healthy: 5% or less of the surface is too thin.
  
  error: more than 5% of the surface is too thin. To thicken the walls, pass this task's id to Repair Printability as input_task_id (for an .stl, .fbx, or .gltf model_url, send the file as model_url instead).
  
  unknown: the model couldn't be measured. If the wall-thickness check itself fails, the task ends FAILED.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Timestamp of when the analysis was computed, in milliseconds since epoch.
Name
consumed_credits
Type
integer
Description
Always 0. This endpoint is free.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}