API Perbaiki kemampuan cetak

Perbaiki model 3D untuk kemampuan cetak FDM — perbaiki tepi non-manifold, permukaan degenerasi, lubang, dan masalah topology lainnya agar mesh siap cetak.

POST/openapi/v1/print/repair

Buat Tugas Perbaiki kemampuan cetak

endpoint ini membuat tugas Perbaiki kemampuan cetak baru. Tugas menjalankan perbaikan topology pada model 3D dan mengembalikan versi yang kedap air dan siap cetak.

Format output sesuai dengan format input. Jika Anda mengirimkan .stl melalui model_url, model_urls.stl pada respons akan berisi mesh yang telah diperbaiki dan bidang format lainnya akan kosong. Jalur input_task_id selalu membaca GLB dari tugas sumber, sehingga output-nya adalah .glb.

Parameter

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

Tekstur yang ada dihapus selama perbaikan karena perubahan geometri. Untuk menambahkan kembali tekstur, gunakan Retexture API pada model yang telah diperbaiki.

  • Name
    model_url
    Type
    string
    Wajib
    Description

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

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Jika diatur ke true, tugas juga merender versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Bidang thumbnail_url yang ada tidak berubah.

Mengembalikan

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

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • parameter tidak ada: 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 format, menggunakan skema yang tidak didukung, atau memiliki ekstensi file yang tidak didukung.
    • File model terlalu besar: isi model_url melebihi 100 MB.
    • Tugas belum berhasil: tugas yang dirujuk masih pending, sedang berlangsung, atau gagal.
    • GLB tidak ada: tugas yang dirujuk tidak memiliki aset GLB untuk diperbaiki.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Harap periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Penyebab umum:

    • Paket gratis: pembuatan tugas memerlukan paket berbayar. Tingkatkan di halaman langganan.
    • Kredit tidak mencukupi: batas kredit ruang kerja telah tercapai.
  • Name
    404 - Not Found
    Description

    Tugas yang dirujuk tidak ada atau dimiliki oleh pengguna lain.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui kuota tugas PENDING atau batas laju.

Request

POST
/openapi/v1/print/repair
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

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

Mengambil Tugas Perbaiki kemampuan cetak

endpoint ini mengambil tugas perbaiki kemampuan cetak berdasarkan ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas perbaiki kemampuan cetak yang akan diambil.

Mengembalikan

Objek Tugas Perbaiki kemampuan cetak. Blok model_urls kosong hingga tugas mencapai SUCCEEDED. Hanya field model_urls yang cocok dengan format input yang akan diisi.

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Hapus Tugas Perbaiki kemampuan cetak

Endpoint ini menghapus secara permanen tugas Perbaiki kemampuan cetak dan output yang telah diperbaiki. Tindakan ini tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID tugas Perbaiki kemampuan cetak yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Request

DELETE
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v1/print/repair

Daftar Tugas Perbaiki kemampuan cetak

Endpoint ini memungkinkan Anda mengambil daftar tugas perbaikan kemampuan cetak.

Parameter

Atribut opsional

  • Name
    page_num
    Type
    integer
    Description

    Nomor halaman untuk paginasi. Dimulai dan secara default bernilai 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Secara default 10 item. Maksimum yang diizinkan adalah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk diurutkan berdasarkan. Nilai yang tersedia:

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

Mengembalikan

Mengembalikan daftar terpaginasi dari Objek Tugas Perbaiki kemampuan cetak.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Streaming Tugas Perbaiki kemampuan cetak

endpoint ini mengalirkan pembaruan real-time untuk tugas Perbaiki kemampuan cetak menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas Perbaiki kemampuan cetak yang akan dialirkan.

Mengembalikan

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

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan field progress dan status yang diperlukan. Blok model_urls dikirim hanya setelah tugas mencapai SUCCEEDED.

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

Objek Tugas Perbaiki kemampuan cetak

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Jenis tugas Perbaiki kemampuan cetak. Nilainya adalah print-repair.

  • 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 bernilai 0. Setelah tugas berhasil, ini akan menjadi 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang mendahului.

    Nilai bidang ini hanya bermakna 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 bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 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 tidak gagal. Lihat Kesalahan untuk detail lebih lanjut.

    • Name
      message
      Type
      string
      Description

      Pesan kesalahan yang menjelaskan apa yang salah.

  • Name
    model_urls
    Type
    object
    Description

    URL yang dapat diunduh untuk model 3D yang telah diperbaiki. Hanya bidang yang cocok dengan format input yang diisi; bidang format lainnya berupa string kosong.

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk GLB yang telah diperbaiki. Diisi ketika input adalah GLB atau ketika input_task_id digunakan.

    • Name
      fbx
      Type
      string
      Description

      Dicadangkan untuk output FBX. Selalu berupa string kosong untuk tugas Perbaiki kemampuan cetak.

    • Name
      obj
      Type
      string
      Description

      URL yang dapat diunduh untuk OBJ yang telah diperbaiki. Diisi ketika input adalah unggahan OBJ.

    • Name
      stl
      Type
      string
      Description

      URL yang dapat diunduh untuk STL yang telah diperbaiki. Diisi ketika input adalah unggahan STL.

    • Name
      usdz
      Type
      string
      Description

      Dicadangkan untuk output USDZ. Selalu berupa string kosong untuk tugas Perbaiki kemampuan cetak.

    • Name
      3mf
      Type
      string
      Description

      Dicadangkan untuk output 3MF. Selalu berupa string kosong untuk tugas Perbaiki kemampuan cetak.

    • Name
      mtl
      Type
      string
      Description

      Dicadangkan untuk output MTL. Selalu berupa string kosong untuk tugas Perbaiki kemampuan cetak.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL gambar pratinjau yang dirender dari model yang telah diperbaiki.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL yang dapat diunduh untuk versi berlatar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, bidang ini dihilangkan.

  • Name
    texture_urls
    Type
    array
    Description

    Selalu berupa array kosong. Perbaikan hanya mempertahankan geometri input dan tidak melakukan re-bake texture.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang dikonsumsi oleh tugas ini. 10 setelah tugas mencapai SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat gagal).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}