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 yang baharu. Tugas ini menilai model 3D dan melaporkan metrik kebolehcetakannya.

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

Parameter

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

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas berjaya yang anda miliki. Jenis tugas yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D, Remesh, dan Retekstur. Tugas tersebut mesti menggunakan Meshy 6 atau lebih baharu (termasuk Meshy 7) 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 melangkau semakan sambungan fail).

Pulangan

Sifat result bagi respons mengandungi id bagi tugas analisis-kebolehcetakan yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter hilang: kedua-dua input_task_id dan model_url tidak diberikan.
- UUID tidak sah: input_task_id bukan UUID yang sah.
- URL model tidak sah: model_url mempunyai format yang salah, 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 tertangguh, sedang dijalankan, atau gagal.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
403 - Forbidden
Description
Tugas tersebut wujud tetapi dimiliki oleh pengguna lain.
Name
404 - Not Found
Description
Punca biasa:
- Tugas tersebut tidak wujud atau telah dipadamkan.
- Tugas tersebut menggunakan model yang lebih lama daripada Meshy 6, atau modenya tidak menghasilkan aset 3D.
- Fail model asas tersebut tidak lagi tersedia dalam storan.
Name
429 - Too Many Requests
Description
Anda telah melebihi kuota tugas-tertangguh 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 Semula Tugas Analisis Kebolehcetakan

Endpoint ini mendapatkan semula tugas analisis-kebolehcetakan mengikut IDnya.

Parameter

Name
id
Type
path
Description
ID tugas analisis-kebolehcetakan yang hendak didapatkan semula.

Pulangan

Objek Tugas Analisis Kebolehcetakan. Medan printability adalah null sehingga tugas 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 memadam secara kekal satu tugas analisis-kebolehcetakan beserta hasil cache-nya. Tindakan ini tidak boleh diterbalikkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas analisis-kebolehcetakan yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas terus berjalan. Kredit bagi tugas yang pekerja (worker) telah mulakan tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pulangan

Memulangkan 200 OK apabila berjaya, atau 409 Conflict apabila tugas sedang 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

Senaraikan Tugasan Analisis Kebolehcetakan

Endpoint ini membolehkan anda mendapatkan senarai tugasan 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 adalah 100 item.
Name
sort_by
Type
string
Description
Medan untuk disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai bernomborkan halaman bagi Objek Tugasan 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

Alirkan Tugas Analisis Kebolehcetakan

Endpoint ini mengalirkan 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 hendak dialirkan.

Pemulangan

Memulangkan aliran Objek Tugas Analisis Kebolehcetakan sebagai Server-Sent Events.

Setiap bingkai membawa objek tugas penuh untuk peringkat tersebut — bentuk yang sama seperti yang dipulangkan oleh endpoint Get — jadi semasa tugas berstatus PENDING atau IN_PROGRESS, medan output hanya belum diisi lagi (null, [] atau {}) dan finished_at adalah null. Blok printability hanya dihantar sebaik sahaja 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.
// 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
}

Objek Tugas Analisis Kebolehcetakan

Name
id
Type
string
Description
Pengenal unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun-k untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas analyze-printability. Nilainya ialah print-analyze.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum bermula, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
preceding_tasks
Type
integer
Description
Kiraan tugas yang mendahului.
Nilai medan ini hanya bermakna jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas tamat, dalam milisaat. Jika tugas belum tamat, sifat ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Cap masa bila hasil tugas akan luput daripada sistem, dalam milisaat. 0 jika tugas belum lagi tamat.
Name
task_error
Type
object
Description
Maklumat ralat jika tugas gagal. Sifat ini adalah null jika tugas tidak gagal. Lihat Ralat untuk maklumat lanjut.
- Name
  message
  Type
  string
  Description
  Mesej ralat yang menerangkan apa yang tidak kena.
Name
printability
Type
object
Description
Hasil penilaian kebolehcetakan. null sehingga tugas mencapai SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versi skema bagi 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 kiraan isu, bersamaan dengan error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Bilangan isu peringkat ralat. Ralat dibangkitkan apabila model tidak kalis air (watertight), mempunyai isi padu bukan-positif, atau mempunyai tepi non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Bilangan isu peringkat amaran. Amaran dibangkitkan 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
  Isi padu model dalam meter padu.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Kiraan tepi non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Kiraan muka degenerat (muka dengan luas sifar atau tidak sah).
  Name
  holes
  Type
  integer
  Description
  Kiraan lubang (gelung sempadan) dalam jejaring.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Cap masa bila analisis tersebut dikira, dalam milisaat sejak epoch.
Name
consumed_credits
Type
integer
Description
Sentiasa 0. Endpoint ini adalah 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
}