API Analisis kemampuan cetak

Analisis model 3D untuk kemampuan cetak FDM — kedap air, volume, lubang, tepi non-manifold, dan permukaan degenerasi.

POST/openapi/v1/print/analyze

Buat Tugas Analisis kemampuan cetak

Endpoint ini membuat tugas analyze-printability baru. Tugas ini mengevaluasi model 3D dan melaporkan metrik kemampuan cetaknya.

Jika tugas input sudah memiliki kemampuan cetak yang di-cache, tugas yang dikembalikan langsung siap dan GET pertama padanya akan mengembalikan hasil analisis tanpa melalui worker.

Parameter

Hanya salah satu dari input_task_id atau model_url yang wajib. Jika keduanya disediakan, input_task_id mendapat prioritas.

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas yang berhasil yang Anda miliki. Jenis tugas yang didukung: Gambar ke 3D, Multi-Gambar ke 3D, Teks ke 3D, Remesh, dan Retexture. Tugas harus menggunakan Meshy 6 (atau model Preview apa pun) dan harus memiliki status SUCCEEDED.

Name
model_url
Type
string
Wajib
Description
URL model 3D untuk dianalisis. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl. Ukuran file maksimum: 100 MB. Harus menggunakan URL http, https, atau data: (URL data melewati pemeriksaan ekstensi).

Mengembalikan

Properti result dari respons berisi id dari tugas analisis kemampuan cetak yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: baik input_task_id maupun model_url tidak disediakan.
- UUID tidak valid: input_task_id bukan UUID yang valid.
- URL model tidak valid: model_url salah bentuk, menggunakan skema yang tidak didukung, atau memiliki ekstensi file yang tidak didukung.
- File model terlalu besar: body model_url melebihi 100 MB.
- Tugas tidak berhasil: tugas yang direferensikan masih tertunda, sedang dalam progress, atau gagal.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
403 - Forbidden
Description
Tugas ada tetapi dimiliki oleh pengguna yang berbeda.
Name
404 - Not Found
Description
Penyebab umum:
- Tugas tidak ada atau telah dihapus.
- Tugas menggunakan model yang lebih lama dari Meshy 6, atau mode-nya tidak menghasilkan asset 3D.
- File model yang mendasarinya tidak lagi tersedia di penyimpanan.
Name
429 - Too Many Requests
Description
Anda telah melampaui kuota tugas tertunda atau batas laju 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

Ambil Tugas Analisis kemampuan cetak

Endpoint ini mengambil tugas analisis kemampuan cetak berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas analisis kemampuan cetak yang akan diambil.

Mengembalikan

Objek Tugas Analisis kemampuan cetak. Field printability bernilai null hingga 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

Hapus Tugas Analisis kemampuan cetak

Endpoint ini menghapus secara permanen tugas analisis kemampuan cetak dan hasil cache-nya. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID tugas analisis kemampuan cetak yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK saat berhasil.

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

Daftar Tugas Analisis kemampuan cetak

endpoint ini memungkinkan Anda mengambil daftar tugas analisis kemampuan cetak.

Parameter

Atribut opsional

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai dan default ke 1.
Name
page_size
Type
integer
Description
Batas ukuran halaman. Default ke 10 item. Maksimum yang diizinkan adalah 50 item.
Name
sort_by
Type
string
Description
Bidang untuk diurutkan berdasarkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menaik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menurun.

Mengembalikan

Mengembalikan daftar terpaginasi dari Objek Tugas Analisis kemampuan cetak.

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

Streaming Tugas Analisis kemampuan cetak

Endpoint ini melakukan streaming pembaruan real-time untuk tugas analyze-printability menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas analyze-printability yang akan di-stream.

Pengembalian

Mengembalikan stream Objek Tugas Analisis kemampuan cetak sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan field progress dan status yang diperlukan. Blok printability hanya dikirim setelah 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 Tugas Analisis kemampuan cetak

Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas analyze-printability. Nilainya adalah print-analyze.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang mendahului.
Nilai bidang ini bermakna hanya jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Stempel waktu saat tugas dibuat, dalam milidetik.
Name
started_at
Type
timestamp
Description
Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil tugas akan kedaluwarsa dari sistem, dalam milidetik. 0 jika tugas belum selesai.
Name
task_error
Type
object
Description
Informasi kesalahan jika tugas gagal. Properti ini adalah null jika tugas belum gagal. Lihat Kesalahan untuk detail lebih lanjut.
- Name
  message
  Type
  string
  Description
  Pesan kesalahan yang menjelaskan apa yang salah.
Name
printability
Type
object
Description
Hasil evaluasi kemampuan cetak. null hingga tugas mencapai SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versi skema dari hasil kemampuan cetak. Saat ini v1.
- Name
  status
  Type
  string
  Description
  Status keseluruhan. Salah satu dari:
  
  healthy: tidak ada kesalahan dan tidak ada peringatan.
  
  warning: setidaknya satu peringatan, tidak ada kesalahan.
  
  error: setidaknya satu kesalahan.
  
  unknown: model tidak dapat dianalisis.
- Name
  issue_count
  Type
  integer
  Description
  Jumlah total masalah, sama dengan error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Jumlah masalah tingkat kesalahan. Kesalahan dimunculkan saat model tidak kedap air, memiliki volume non-positif, atau memiliki tepi non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Jumlah masalah tingkat peringatan. Peringatan dimunculkan saat model berisi permukaan degenerasi atau lubang.
- Name
  metrics
  Type
  object
  Description
  Metrik geometri mentah yang dikembalikan oleh evaluator.
  Name
  is_watertight
  Type
  boolean
  Description
  true saat mesh tidak memiliki tepi batas (yaitu, tertutup).
  Name
  volume
  Type
  number
  Description
  Volume model dalam meter kubik.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Jumlah tepi non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Jumlah permukaan degenerasi (permukaan tanpa area atau tidak valid).
  Name
  holes
  Type
  integer
  Description
  Jumlah lubang (loop batas) dalam mesh.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Stempel waktu saat analisis dihitung, dalam milidetik sejak epoch.
Name
consumed_credits
Type
integer
Description
Selalu 0. Endpoint ini gratis.

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
}