API Perbaiki Kemampuan Cetak

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

POST/openapi/v1/print/repair

Buat Tugas Perbaiki Kemampuan Cetak

Endpoint ini membuat tugas perbaiki kemampuan cetak yang baru. Tugas ini 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 outputnya adalah .glb.

Parameter

Hanya salah satu dari input_task_id atau model_url yang diperlukan. Jika keduanya disediakan, input_task_id memiliki prioritas.

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

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas yang berhasil Anda miliki. Jenis tugas yang didukung: Gambar ke 3D, Multi-Gambar ke 3D, Teks ke 3D, Remesh, dan Retexture. Tugas harus memiliki status SUCCEEDED dan harus menghasilkan aset GLB.

Name
model_url
Type
string
Wajib
Description
URL dari model 3D untuk diperbaiki. 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).

Name
alpha_thumbnail
Type
boolean
default false
Description
Ketika 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 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 tidak benar, menggunakan skema yang tidak didukung, atau memiliki ekstensi file yang tidak didukung.
- File model terlalu besar: isi model_url melebihi 100 MB.
- Tugas tidak berhasil: tugas yang dirujuk masih tertunda, dalam progress, atau gagal.
- GLB hilang: tugas yang dirujuk tidak memiliki aset GLB untuk diperbaiki.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan 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 melebihi kuota tugas tertunda atau batas laju.

Permintaan

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

Respons

{
  "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 dari tugas perbaiki kemampuan cetak yang akan diambil.

Mengembalikan

Objek Tugas Perbaiki Kemampuan Cetak. Blok model_urls kosong sampai tugas mencapai SUCCEEDED. Hanya field model_urls yang sesuai dengan format input yang diisi.

Permintaan

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

Respon

{
  "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": "",
    "gltf": "",
    "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 secara permanen menghapus tugas perbaiki kemampuan cetak dan hasil perbaikannya. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

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

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Permintaan

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

Respon

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

Daftar Tugas Perbaiki Kemampuan Cetak

Endpoint ini memungkinkan Anda untuk mengambil daftar tugas perbaikan 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 mengurutkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar paginasi dari Objek Tugas Perbaiki Kemampuan Cetak.

Permintaan

GET

/openapi/v1/print/repair

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

Respon

[
  {
    "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=***",
      "gltf": "",
      "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 waktu nyata untuk tugas perbaiki kemampuan cetak menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas perbaiki kemampuan cetak yang akan dialirkan.

Mengembalikan

Mengembalikan aliran Objek Tugas Perbaiki Kemampuan Cetak sebagai Server-Sent Events.

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

Permintaan

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

Aliran Respons

// 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=***",
    "gltf": "",
    "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
Pengenal unik untuk tugas ini. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apapun tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas perbaiki-kemampuan-cetak. Nilainya adalah print-repair.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress dari 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 sebelumnya.
Nilai dari bidang ini hanya berarti jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Stempel waktu ketika tugas dibuat, dalam milidetik.
Name
started_at
Type
timestamp
Description
Stempel waktu ketika tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu ketika tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 0.
Name
expires_at
Type
timestamp
Description
Stempel waktu ketika 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 bernilai null jika tugas tidak gagal. Lihat Kesalahan untuk lebih jelasnya.
- 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 sesuai dengan format input yang diisi; bidang format lainnya adalah 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
  gltf
  Type
  string
  Description
  URL yang dapat diunduh untuk GLTF yang telah diperbaiki. Diisi ketika input adalah unggahan GLTF.
- Name
  fbx
  Type
  string
  Description
  URL yang dapat diunduh untuk FBX yang telah diperbaiki. Diisi ketika input adalah unggahan FBX.
- 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
  Direservasi untuk output USDZ. Selalu berupa string kosong untuk tugas perbaiki-kemampuan-cetak.
- Name
  3mf
  Type
  string
  Description
  Direservasi untuk output 3MF. Selalu berupa string kosong untuk tugas perbaiki-kemampuan-cetak.
- Name
  mtl
  Type
  string
  Description
  Direservasi untuk output MTL. Selalu berupa string kosong untuk tugas perbaiki-kemampuan-cetak.
Name
thumbnail_url
Type
string
Description
URL dari gambar pratinjau yang dirender dari model yang telah diperbaiki.
Name
alpha_thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk versi latar 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 mengolah ulang 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 jika 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=***",
    "gltf": "",
    "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
}