API Analisis kebolehcetakan

Analisis model 3D untuk kebolehcetakan FDM — kekedapan air, isi padu, lubang, tepi non-manifold, dan muka degenerat.

POST/openapi/v1/print/analyze

Cipta Tugas Analisis kebolehcetakan

Endpoint ini mencipta tugas analisis kebolehcetakan baharu. Tugas ini menilai model 3D dan melaporkan metrik kebolehcetakannya.

Jika tugas input sudah mempunyai kebolehcetakan yang dicache, tugas yang dikembalikan akan tersedia dengan serta-merta dan GET pertama padanya akan mengembalikan hasil analisis tanpa melalui worker.

Parameter

Hanya satu daripada input_task_id atau model_url diperlukan. Jika kedua-duanya diberikan, input_task_id mengambil keutamaan.

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas yang berjaya yang anda miliki. Jenis tugas yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D, Remesh, dan Retekstur. Tugas mesti menggunakan Meshy 6 (atau mana-mana model Preview) dan mesti mempunyai status SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
URL model 3D untuk dianalisis. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Saiz fail maksimum: 100 MB. Mesti menggunakan http, https, atau URL data: (URL data memintas semakan sambungan).

Pulangan

Sifat result dalam respons mengandungi id bagi tugas analisis kebolehcetakan yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter tiada: input_task_id mahupun model_url tidak diberikan.
- UUID tidak sah: input_task_id bukan UUID yang sah.
- URL model tidak sah: model_url tidak dibentuk dengan betul, menggunakan skema yang tidak disokong, atau mempunyai sambungan fail yang tidak disokong.
- Fail model terlalu besar: badan model_url melebihi 100 MB.
- Tugas tidak berjaya: tugas yang dirujuk masih belum selesai, sedang diproses, atau gagal.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
403 - Forbidden
Description
Tugas wujud tetapi dimiliki oleh pengguna lain.
Name
404 - Not Found
Description
Punca biasa:
- Tugas tidak wujud atau telah dipadamkan.
- Tugas menggunakan model yang lebih lama daripada Meshy 6, atau modenya tidak menghasilkan asset 3D.
- Fail model asas tidak lagi tersedia dalam storan.
Name
429 - Too Many Requests
Description
Anda telah melebihi kuota tugas tertunda atau had kadar anda.

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

Dapatkan Tugasan Analisis kebolehcetakan

Endpoint ini mendapatkan tugasan analisis kebolehcetakan berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugasan analisis kebolehcetakan untuk didapatkan.

Pulangan

Objek Tugasan Analisis kebolehcetakan. Medan printability ialah null sehingga tugasan mencapai 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

Padam Tugas Analisis kebolehcetakan

Endpoint ini memadamkan secara kekal tugas Analisis kebolehcetakan dan hasil cachenya. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas Analisis kebolehcetakan untuk dipadamkan.

Mengembalikan

Mengembalikan 200 OK apabila berjaya.

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

Senarai Tugas Analisis kebolehcetakan

endpoint ini membolehkan anda mendapatkan senarai tugas analisis-kebolehcetakan.

Parameter

Atribut pilihan

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan lalai kepada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Lalai kepada 10 item. Maksimum yang dibenarkan ialah 50 item.
Name
sort_by
Type
string
Description
Medan untuk diisih mengikut. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan dalam tertib menaik.
- -created_at: Isih mengikut masa penciptaan dalam tertib menurun.

Pulangan

Mengembalikan senarai berhalaman Objek Tugas Analisis kebolehcetakan.

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

Strimkan Tugas Analisis kebolehcetakan

Endpoint ini menstrim kemas kini masa nyata untuk tugas analisis kebolehcetakan menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas analisis kebolehcetakan yang akan distrim.

Pulangan

Mengembalikan strim Objek Tugas Analisis kebolehcetakan sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan menyertakan medan progress dan status yang diperlukan. Blok printability dihantar hanya selepas tugas mencapai 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
}

Objek Tugasan Analisis kebolehcetakan

Name
id
Type
string
Description
Pengenal unik untuk tugasan. Walaupun kami menggunakan UUID boleh diisih-k untuk id tugasan sebagai perincian pelaksanaan, anda tidak sepatutnya membuat sebarang andaian tentang format id.
Name
type
Type
string
Description
Jenis tugasan analisis kebolehcetakan. Nilainya ialah print-analyze.
Name
status
Type
string
Description
Status tugasan. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugasan. Jika tugasan belum dimulakan lagi, sifat ini akan menjadi 0. Setelah tugasan berjaya, ini akan menjadi 100.
Name
preceding_tasks
Type
integer
Description
Bilangan tugasan terdahulu.
Nilai medan ini hanya bermakna jika status tugasan ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa apabila tugasan dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa apabila tugasan dimulakan, dalam milisaat. Jika tugasan belum dimulakan lagi, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa apabila tugasan selesai, dalam milisaat. Jika tugasan belum selesai lagi, sifat ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Cap masa apabila hasil tugasan akan tamat tempoh daripada sistem, dalam milisaat. 0 jika tugasan belum selesai lagi.
Name
task_error
Type
object
Description
Maklumat ralat jika tugasan telah gagal. Sifat ini ialah null jika tugasan belum gagal. Lihat Ralat untuk butiran lanjut.
- Name
  message
  Type
  string
  Description
  Mesej ralat yang menerangkan perkara yang berlaku.
Name
printability
Type
object
Description
Hasil penilaian kebolehcetakan. null sehingga tugasan mencapai SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versi skema hasil kebolehcetakan. Pada masa ini v1.
- Name
  status
  Type
  string
  Description
  Status keseluruhan. Salah satu daripada:
  
  healthy: tiada ralat dan tiada amaran.
  
  warning: sekurang-kurangnya satu amaran, tiada ralat.
  
  error: sekurang-kurangnya satu ralat.
  
  unknown: model tidak dapat dianalisis.
- Name
  issue_count
  Type
  integer
  Description
  Jumlah bilangan isu, sama dengan error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Bilangan isu tahap ralat. Ralat dicetuskan apabila model tidak kedap air, mempunyai isipadu bukan positif, atau mempunyai tepi non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Bilangan isu tahap amaran. Amaran dicetuskan apabila model mengandungi muka degenerat atau lubang.
- Name
  metrics
  Type
  object
  Description
  Metrik geometri mentah yang dikembalikan oleh penilai.
  Name
  is_watertight
  Type
  boolean
  Description
  true apabila jejaring tidak mempunyai tepi sempadan (iaitu, tertutup).
  Name
  volume
  Type
  number
  Description
  Isipadu model dalam meter padu.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Bilangan tepi non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Bilangan muka degenerat (muka sifar luas atau tidak sah).
  Name
  holes
  Type
  integer
  Description
  Bilangan lubang (gelung sempadan) dalam jejaring.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Cap masa apabila analisis dikira, dalam milisaat sejak epoch.
Name
consumed_credits
Type
integer
Description
Sentiasa 0. Endpoint ini percuma.

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
}