API Analisis Kebolehcetakan

Menganalisis model 3D untuk kebolehcetakan FDM — ketahanan air, isipadu, lubang, tepi non-manifold, dan muka degenerat.

POST/openapi/v1/print/analyze

Cipta Tugas Analisis Kebolehcetakan

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

Jika tugas input sudah mempunyai kebolehcetakan yang di-cache, tugas yang dikembalikan akan sedia serta-merta dan GET pertama padanya akan mengembalikan hasil analisis tanpa melalui pekerja.

Parameter

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

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi 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 lebih baru (termasuk Meshy 7) dan mesti mempunyai status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    URL bagi 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 pemeriksaan sambungan).

Pulangan

Properti 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 hilang: sama ada input_task_id atau model_url tidak disediakan.
    • UUID tidak sah: input_task_id bukan UUID yang sah.
    • URL model tidak sah: model_url tidak berbentuk 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 menunggu, dalam progress, 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 dipadam.
    • Tugas menggunakan model yang lebih lama daripada Meshy 6, atau modnya tidak menghasilkan aset 3D.
    • Fail model asas tidak lagi tersedia dalam storan.
  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi kuota tugas yang menunggu atau had kadar anda.

Permintaan

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"
  }'

Respons

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/analyze/:id

Dapatkan Tugas Analisis Kebolehcetakan

Endpoint ini mendapatkan tugas analisis kebolehcetakan berdasarkan ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas analisis kebolehcetakan yang ingin didapatkan.

Mengembalikan

Objek Tugas Analisis Kebolehcetakan. Medan kebolehcetakan adalah null sehingga tugas mencapai SUCCEEDED.

Permintaan

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}"

Respons

{
  "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 yang disimpan dalam cache. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas analisis kebolehcetakan untuk dipadamkan.

Pemulangan

Mengembalikan 200 OK jika berjaya.

Permintaan

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}"

Respons

// 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 disusun. Nilai yang tersedia:

    • +created_at: Susun mengikut masa penciptaan dalam susunan menaik.
    • -created_at: Susun mengikut masa penciptaan dalam susunan menurun.

Pulangan

Mengembalikan senarai berpenomboran halaman bagi Objek Tugas Analisis Kebolehcetakan.

Permintaan

GET
/openapi/v1/print/analyze
curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Respons

[
  {
    "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

    Pengenal pasti unik untuk tugas analisis kebolehcetakan untuk 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 kebolehcetakan dihantar hanya apabila tugas mencapai SUCCEEDED.

Permintaan

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 Kebolehcetakan

  • Name
    id
    Type
    string
    Description

    Pengenal unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh diurutkan secara k untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas analisis kebolehcetakan. 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

    Kemajuan tugas. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas terdahulu.

    Nilai medan ini hanya bermakna jika status tugas adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa ketika tugas dicipta, dalam milisaat.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa ketika tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa ketika tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa ketika hasil tugas akan tamat tempoh dari sistem, dalam milisaat. 0 jika tugas belum selesai.

  • Name
    task_error
    Type
    object
    Description

    Maklumat ralat jika tugas telah 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 salah.

  • Name
    printability
    Type
    object
    Description

    Hasil penilaian kebolehcetakan. null sehingga tugas mencapai SUCCEEDED.

    • Name
      _version
      Type
      string
      Description

      Versi skema hasil kebolehcetakan. Kini 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 timbul apabila model tidak kedap air, mempunyai isipadu tidak positif, atau mempunyai tepi non-manifold.

    • Name
      warning_count
      Type
      integer
      Description

      Bilangan isu tahap amaran. Amaran timbul 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 dengan luas sifar atau tidak sah).

      • Name
        holes
        Type
        integer
        Description

        Bilangan lubang (gelung sempadan) dalam jejaring.

    • Name
      evaluated_at
      Type
      timestamp
      Description

      Cap masa ketika analisis 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
}