Analyze Printability API

Suriin ang isang 3D na modelo para sa FDM printability — watertightness, volume, mga butas, non-manifold edges, at degenerate faces.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Ang endpoint na ito ay lumilikha ng bagong analyze-printability task. Sinusuri ng task ang isang 3D model at iniuulat ang mga printability metrics nito.

Kung ang input task ay mayroon na cached printability, ang ibinalik na task ay agad na handa at ang unang GET dito ay ibabalik ang analysis result nang hindi na dumadaan sa worker.

Mga Parameter

Kailangan lang ang isa sa input_task_id o model_url. Kung ibinigay ang dalawa, ang input_task_id ang mananaig.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang matagumpay na task na sa iyo. Suportadong mga uri ng task: Image to 3D, Multi-Image to 3D, Text to 3D, Remesh, at Retexture. Dapat gumamit ang task ng Meshy 6 o mas bago (kasama ang Meshy 7) at dapat mayroon itong status na SUCCEEDED.

Name
model_url
Type
string
Kinakailangan
Description
URL ng isang 3D model na susuriin. Suportadong mga format: .glb, .gltf, .obj, .fbx, .stl. Pinakamataas na laki ng file: 100 MB. Dapat gumamit ng http, https, o isang data: URL (ang data URLs ay lumalagpas sa mga extension check).

Mga Ibabalik

Ang result property ng response ay naglalaman ng id ng bagong likhang analyze-printability task.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang mga dahilan:
- Nawawalang parameter: hindi ibinigay ang input_task_id o model_url.
- Hindi wastong UUID: hindi wastong UUID ang input_task_id.
- Hindi wastong model URL: hindi wasto ang pagkabuo ng model_url, gumagamit ito ng hindi suportadong scheme, o may hindi suportadong file extension.
- Sobrang laki ng model file: lumagpas sa 100 MB ang body ng model_url.
- Hindi matagumpay ang task: ang tinutukoy na task ay nasa pending, in progress, o failed pa.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Mangyaring suriin ang iyong API key.
Name
403 - Forbidden
Description
Umiiral ang task ngunit pag-aari ito ng ibang user.
Name
404 - Not Found
Description
Karaniwang mga dahilan:
- Hindi umiiral ang task o naburang na ito.
- Gumagamit ang task ng model na mas luma kaysa Meshy 6, o hindi nagbubunga ang mode nito ng 3D asset.
- Hindi na available sa storage ang pinagbabatayang model file.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang iyong pending-task quota o 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

Kunin ang Analyze Printability Task

Ang endpoint na ito ay kinukuha ang analyze-printability task gamit ang ID nito.

Mga Parameter

Name
id
Type
path
Description
Ang ID ng analyze-printability task na kukunin.

Mga Ibabalik

Ang Analyze Printability Task Object. Ang field na printability ay null hanggang maabot ng task ang 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

Burahin ang isang Analyze Printability Task

Permanenteng binubura ng endpoint na ito ang isang analyze-printability task at ang naka-cache nitong resulta. Hindi na maaaring bawiin ang aksyong ito.

Path Parameters

Name
id
Type
path
Description
Ang ID ng analyze-printability task na buburahin.

Katayuan ng Task

Ang task na PENDING pa ay binubura at ang mga credits na nagamit noong oras ng paglikha nito ay ire-refund.

Ang task na IN_PROGRESS na ay hindi maaaring burahin: ang request ay tatanggihan na may 409 Conflict at magpapatuloy pa ring tumatakbo ang task. Ang mga credits para sa task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya ang pagbura nito habang tumatakbo pa ay mawawala sa iyo ang mga credits at ang resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito burahin.

Ang task na nasa terminal na estado (SUCCEEDED, FAILED, o CANCELED) ay binubura nang walang refund.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay 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

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kumuha ng listahan ng mga analyze-printability tasks.

Mga Parameter

Mga opsyonal na attribute

Name
page_num
Type
integer
Description
Numero ng page para sa pagination. Nagsisimula at default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa laki ng page. Ang default ay 10 items. Ang maximum na pinapayagan ay 100 items.
Name
sort_by
Type
string
Description
Field na gagamitin sa pag-sort. Mga available na value:
- +created_at: I-sort ayon sa oras ng paglikha sa ascending order.
- -created_at: I-sort ayon sa oras ng paglikha sa descending order.

Ibinabalik

Nagbabalik ng paginated na listahan ng 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

Ang endpoint na ito ay nagstream ng mga real-time update para sa isang analyze-printability task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Ang natatanging identifier para sa analyze-printability task na istream.

Mga Ibinabalik

Nagbabalik ng stream ng Analyze Printability Task Objects bilang Server-Sent Events.

Bawat frame ay may kompletong task object para sa yugto — ang parehong hugis na ibinabalik ng Get endpoint — kaya habang ang task ay PENDING o IN_PROGRESS, ang output fields ay hindi pa lang napopulate (null, [] o {}) at ang finished_at ay null. Ang printability block ay ipinapadala lamang kapag naabot na ng task ang 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
Kakaiba/natatanging identifier para sa task. Bagaman gumagamit kami ng k-sortable UUID para sa mga task id bilang implementation detail, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng analyze-printability task. Ang value ay print-analyze.
Name
status
Type
string
Description
Status ng task. Ang posibleng mga value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay 0. Kapag nagtagumpay na ang task, ito ay magiging 100.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Ang value ng field na ito ay may kahulugan lamang kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp ng kung kailan ginawa ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp ng kung kailan nasimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay 0.
Name
finished_at
Type
timestamp
Description
Timestamp ng kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay 0.
Name
expires_at
Type
timestamp
Description
Timestamp ng kung kailan mag-e-expire ang resulta ng task mula sa sistema, sa milliseconds. 0 kung hindi pa natatapos ang task.
Name
task_error
Type
object
Description
Impormasyon ng error kung nabigo ang task. Ang property na ito ay null kung hindi nabigo ang task. Tingnan ang Errors para sa karagdagang detalye.
- Name
  message
  Type
  string
  Description
  Mensahe ng error na naglalarawan kung ano ang nagkamali.
Name
printability
Type
object
Description
Resulta ng ebalwasyon ng printability. null hanggang maabot ng task ang SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Schema version ng resulta ng printability. Kasalukuyang v1.
- Name
  status
  Type
  string
  Description
  Pangkalahatang status. Isa sa:
  
  healthy: walang errors at walang warnings.
  
  warning: may kahit isang warning, walang errors.
  
  error: may kahit isang error.
  
  unknown: hindi na-analyze ang model.
- Name
  issue_count
  Type
  integer
  Description
  Kabuuang bilang ng mga isyu, katumbas ng error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Bilang ng mga isyu sa antas ng error. Nagkakaroon ng Errors kapag ang model ay hindi watertight, may non-positive volume, o may non-manifold edges.
- Name
  warning_count
  Type
  integer
  Description
  Bilang ng mga isyu sa antas ng warning. Nagkakaroon ng warnings kapag ang model ay may degenerate faces o holes.
- Name
  metrics
  Type
  object
  Description
  Hilaw na sukatan ng heometriya na ibinabalik ng evaluator.
  Name
  is_watertight
  Type
  boolean
  Description
  true kapag ang mesh ay walang boundary edges (ibig sabihin, ito ay sarado).
  Name
  volume
  Type
  number
  Description
  Dami/volume ng model sa cubic meters.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Bilang ng non-manifold edges.
  Name
  degenerate_faces
  Type
  integer
  Description
  Bilang ng degenerate faces (zero-area o invalid na mga face).
  Name
  holes
  Type
  integer
  Description
  Bilang ng mga butas (boundary loops) sa mesh.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Timestamp ng kung kailan kinompyut ang pagsusuri, sa milliseconds mula sa epoch.
Name
consumed_credits
Type
integer
Description
Palaging 0. Libre ang endpoint na ito.

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
}