API Baiki Kebolehcetakan

Baiki model 3D untuk kebolehcetakan FDM — betulkan tepi non-manifold, muka degenerat, lubang, dan isu topology lain supaya jejaring sedia untuk dicetak.

POST/openapi/v1/print/repair

Cipta Tugas Baiki Kebolehcetakan

Endpoint ini mencipta tugas baiki-kebolehcetakan yang baharu. Tugas ini menjalankan pembaikan topology pada model 3D dan mengembalikan versi kalis air (watertight) yang sedia untuk dicetak.

Format output sepadan dengan format input. Jika anda menghantar .stl melalui model_url, model_urls.stl pada respons akan menyimpan jejaring yang telah dibaiki dan medan format lain akan kosong. Laluan input_task_id sentiasa membaca GLB tugas sumber, jadi outputnya adalah .glb.

Parameter

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

Tekstur sedia ada dialih keluar semasa pembaikan disebabkan perubahan geometri. Untuk menambah semula tekstur, gunakan API Retekstur pada model yang telah dibaiki.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas yang berjaya dan dimiliki oleh anda. Jenis tugas yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D, Remesh, dan Retekstur. Tugas mesti mempunyai status SUCCEEDED dan mesti telah menghasilkan aset GLB.

Name
model_url
Type
string
Diperlukan
Description
URL bagi model 3D yang hendak dibaiki. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Saiz fail maksimum: 100 MB. Mesti menggunakan http, https, atau URL data: (URL data memintas semakan sambungan fail).

Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugas ini juga akan merender versi pratonton latar belakang telus (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url sedia ada tidak berubah.

Pemulangan (Returns)

Sifat result pada respons mengandungi id bagi tugas baiki-kebolehcetakan yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter hilang: kedua-dua input_task_id dan model_url tidak disediakan.
- UUID tidak sah: input_task_id bukan UUID yang sah.
- URL model tidak sah: model_url cacat, menggunakan skema yang tidak disokong, atau mempunyai sambungan fail yang tidak disokong.
- Fail model terlalu besar: badan model_url melebihi 100 MB.
- Tugas belum berjaya: tugas yang dirujuk masih tertunda, sedang berjalan, atau gagal.
- GLB hilang: tugas yang dirujuk tiada aset GLB untuk dibaiki.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Punca biasa:
- Pelan percuma: penciptaan tugas memerlukan pelan berbayar. Naik taraf di halaman langganan.
- Kredit tidak mencukupi: had kredit ruang kerja telah dicapai.
Name
404 - Not Found
Description
Tugas yang dirujuk tidak wujud atau dimiliki oleh pengguna lain.
Name
429 - Too Many Requests
Description
Anda telah melebihi kuota tugas-tertunda atau had kadar anda.

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

Dapatkan Semula Tugas Baiki Kebolehcetakan

Endpoint ini mendapatkan semula tugas baiki-kebolehcetakan mengikut ID-nya.

Parameter

Name
id
Type
path
Description
ID bagi tugas baiki-kebolehcetakan yang hendak didapatkan semula.

Pemulangan

Objek Tugas Baiki Kebolehcetakan. Blok model_urls adalah kosong sehingga tugas mencapai status SUCCEEDED. Hanya medan model_urls yang sepadan dengan format input 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": "",
    "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

Padam Tugas Baiki Kebolehcetakan

Endpoint ini memadam secara kekal tugas baiki kebolehcetakan beserta output yang telah dibaiki. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugas baiki kebolehcetakan yang hendak dipadam.

Status Tugas

Tugas yang masih berstatus PENDING akan dipadam dan kredit yang telah digunakan semasa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas tersebut terus berjalan. Kredit bagi tugas yang sudah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa sedang berjalan akan menyebabkan anda kehilangan kredit dan hasilnya sekali gus. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam keadaan akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Nilai Pulangan

Memulangkan 200 OK jika berjaya, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

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

// 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/repair

List Repair Printability Tasks

Endpoint ini membolehkan anda mendapatkan senarai tugas repair-printability.

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 100 item.
Name
sort_by
Type
string
Description
Medan untuk isihan. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan dalam susunan menaik.
- -created_at: Isih mengikut masa penciptaan dalam susunan menurun.

Pulangan

Mengembalikan senarai berhalaman Objek Tugas Baiki Kebolehcetakan.

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=***",
      "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

Alirkan Tugas Baiki Kebolehcetakan

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas baiki-kebolehcetakan menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas baiki-kebolehcetakan yang hendak dialirkan.

Pulangan

Memulangkan aliran Objek Tugas Baiki Kebolehcetakan sebagai Server-Sent Events.

Setiap bingkai membawa objek tugas penuh untuk peringkat tersebut — bentuk yang sama dengan yang dipulangkan oleh endpoint Get — jadi semasa tugas berstatus PENDING atau IN_PROGRESS medan output hanya belum diisi lagi (null, [] atau {}) dan finished_at adalah null. Blok model_urls hanya dihantar sebaik sahaja 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.
// 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-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
}

The Repair Printability Task Object

Name
id
Type
string
Description
Pengenal unik untuk tugas. Walaupun kami menggunakan k-sortable UUID untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas repair-printability. Nilainya adalah print-repair.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin adalah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum bermula, sifat ini akan menjadi 0. Setelah tugas berjaya, ia akan menjadi 100.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului.
Nilai medan ini bermakna hanya jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas dimulakan, dalam milisaat. Jika tugas belum bermula, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Cap masa bila keputusan tugas akan luput daripada sistem, dalam milisaat. 0 jika tugas belum selesai.
Name
task_error
Type
object
Description
Maklumat ralat jika tugas 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 tidak berjalan lancar.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk model 3D yang telah dibaiki. Hanya medan yang sepadan dengan format input akan diisi; medan format lain adalah rentetan kosong.
- Name
  glb
  Type
  string
  Description
  URL yang boleh dimuat turun untuk GLB yang telah dibaiki. Diisi apabila input adalah GLB atau apabila input_task_id digunakan.
- Name
  gltf
  Type
  string
  Description
  URL yang boleh dimuat turun untuk GLTF yang telah dibaiki. Diisi apabila input adalah muat naik GLTF.
- Name
  fbx
  Type
  string
  Description
  URL yang boleh dimuat turun untuk FBX yang telah dibaiki. Diisi apabila input adalah muat naik FBX.
- Name
  obj
  Type
  string
  Description
  URL yang boleh dimuat turun untuk OBJ yang telah dibaiki. Diisi apabila input adalah muat naik OBJ.
- Name
  stl
  Type
  string
  Description
  URL yang boleh dimuat turun untuk STL yang telah dibaiki. Diisi apabila input adalah muat naik STL.
- Name
  usdz
  Type
  string
  Description
  Dikhaskan untuk output USDZ. Sentiasa rentetan kosong untuk tugas repair-printability.
- Name
  3mf
  Type
  string
  Description
  Dikhaskan untuk output 3MF. Sentiasa rentetan kosong untuk tugas repair-printability.
- Name
  mtl
  Type
  string
  Description
  Dikhaskan untuk output MTL. Sentiasa rentetan kosong untuk tugas repair-printability.
Name
thumbnail_url
Type
string
Description
URL imej pratonton yang dirender daripada model yang telah dibaiki.
Name
alpha_thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk versi latar belakang lutsinar (RGBA) daripada thumbnail_url. Hanya wujud apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, medan ini ditinggalkan.
Name
texture_urls
Type
array
Description
Sentiasa tatasusunan kosong. Pembaikan hanya mengekalkan geometri input dan tidak membakar semula tekstur.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. 10 sebaik sahaja tugas mencapai SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan apabila 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
}