API Analisis kemampuan cetak

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

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Endpoint ini membuat task analisis kemampuan cetak baru. Task ini mengevaluasi model 3D dan melaporkan metrik kemampuan cetaknya.

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

Parameter

Hanya salah satu dari input_task_id atau model_url yang wajib diisi. Jika keduanya diberikan, input_task_id akan diprioritaskan.

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari task yang berhasil dan Anda miliki. Tipe task yang didukung: Gambar ke 3D, Multi-Gambar ke 3D, Teks ke 3D, Remesh, dan Retexture. Task harus menggunakan Meshy 6 atau lebih baru (termasuk Meshy 7) dan harus memiliki status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wajib
    Description

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

Returns

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

Failure Modes

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: baik input_task_id maupun model_url tidak diberikan.
    • UUID tidak valid: input_task_id bukan UUID yang valid.
    • URL model tidak valid: model_url salah format, menggunakan skema yang tidak didukung, atau memiliki ekstensi file yang tidak didukung.
    • File model terlalu besar: isi model_url melebihi 100 MB.
    • Task belum berhasil: task yang dirujuk masih pending, sedang berjalan, atau gagal.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    403 - Forbidden
    Description

    Task ada, tetapi dimiliki oleh pengguna lain.

  • Name
    404 - Not Found
    Description

    Penyebab umum:

    • Task tidak ada atau telah dihapus.
    • Task menggunakan model yang lebih lama dari Meshy 6, atau mode-nya tidak menghasilkan aset 3D.
    • File model yang mendasarinya sudah tidak tersedia lagi di penyimpanan.
  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi kuota task 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

Mengambil Task Analisis Kemampuan Cetak

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID dari task analisis kemampuan cetak yang akan diambil.

Returns

Objek Task Analisis Kemampuan Cetak. Kolom printability bernilai null hingga task mencapai status 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

Menghapus Task Analisis Kemampuan Cetak

Endpoint ini menghapus secara permanen sebuah task analisis kemampuan cetak beserta hasil yang telah di-cache. Tindakan ini tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID dari task analisis kemampuan cetak yang akan dihapus.

Status Task

Task yang masih berstatus PENDING akan dihapus dan kredit yang digunakan pada saat pembuatan akan dikembalikan.

Task yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan task akan terus berjalan. Kredit untuk task yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga statusnya mencapai SUCCEEDED, FAILED, atau CANCELED, lalu hapus task tersebut.

Task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Hasil Pengembalian

Mengembalikan 200 OK jika berhasil, atau 409 Conflict ketika task berstatus 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

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 defaultnya adalah 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Defaultnya 10 item. Maksimum yang diizinkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk pengurutan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.

Returns

Mengembalikan daftar berpaginasi 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

Stream an Analyze Printability Task

Endpoint ini melakukan streaming pembaruan secara real-time untuk tugas analisis kemampuan cetak menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas analisis kemampuan cetak yang akan di-stream.

Returns

Mengembalikan stream Analyze Printability Task Objects sebagai Server-Sent Events.

Setiap frame membawa objek tugas lengkap untuk tahap tersebut — bentuk yang sama dengan yang dikembalikan oleh endpoint Get — sehingga selama tugas berstatus PENDING atau IN_PROGRESS, field output belum terisi (null, [] atau {}) dan finished_at bernilai null. Blok printability hanya dikirim setelah tugas mencapai status 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 Task Analisis Kemampuan Cetak

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara k-sortable untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis task analyze-printability. Nilainya adalah print-analyze.

  • Name
    status
    Type
    string
    Description

    Status task. Nilai yang memungkinkan adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilainya akan menjadi 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang mendahului.

    Nilai dari field ini hanya bermakna jika status task adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat task dibuat, dalam milidetik.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil task akan kedaluwarsa dari sistem, dalam milidetik. 0 jika task belum selesai.

  • Name
    task_error
    Type
    object
    Description

    Informasi kesalahan jika task gagal. Properti ini bernilai null jika task tidak 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 sampai task mencapai status 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 ada satu peringatan, tidak ada kesalahan.
      • error: setidaknya ada 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 muncul ketika model tidak watertight, memiliki volume non-positif, atau memiliki tepi non-manifold.

    • Name
      warning_count
      Type
      integer
      Description

      Jumlah masalah tingkat peringatan. Peringatan muncul ketika model memiliki permukaan degenerasi atau lubang.

    • Name
      metrics
      Type
      object
      Description

      Metrik geometri mentah yang dikembalikan oleh evaluator.

      • Name
        is_watertight
        Type
        boolean
        Description

        true jika 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 dengan area nol atau tidak valid).

      • Name
        holes
        Type
        integer
        Description

        Jumlah lubang (loop batas) pada 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
}