Analyze Printability API

Analyze a 3D model for FDM printability — watertightness, volume, holes, non-manifold edges, and degenerate faces.

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.

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.

Parameters

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

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

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.
    • Task not succeeded: the referenced task is still pending, in progress, or failed.
  • 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"
  }'

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.

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

Returns

Returns 200 OK on success.

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

// Returns 200 Ok on success.
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 50 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.

For PENDING or IN_PROGRESS tasks, the response stream will only include the necessary progress and status fields. 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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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.
    • 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.

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