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 dicetak.

POST/openapi/v1/print/repair

Create a Repair Printability Task

Endpoint ini membuat task perbaikan kemampuan cetak (repair-printability) baru. Task ini menjalankan perbaikan topology pada model 3D dan mengembalikan versi yang watertight dan siap cetak.

Format output sesuai dengan format input. Jika Anda mengirimkan .stl melalui model_url, model_urls.stl pada respons akan menyimpan mesh yang telah diperbaiki dan kolom format lainnya akan kosong. Path input_task_id selalu membaca GLB dari task sumber, sehingga outputnya adalah .glb.

Parameter

Hanya salah satu dari input_task_id atau model_url yang wajib diisi. Jika keduanya diberikan, input_task_id memiliki prioritas.

Texture yang sudah ada akan dihapus selama proses perbaikan karena adanya perubahan geometri. Untuk menambahkan kembali texture, gunakan Retexture API pada model yang telah diperbaiki.

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari task yang berhasil dan Anda miliki. Jenis task yang didukung: Image to 3D, Multi-Image to 3D, Text to 3D, Remesh, dan Retexture. Task tersebut harus memiliki status SUCCEEDED dan harus telah menghasilkan asset GLB.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    URL model 3D yang akan diperbaiki. 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).

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Jika disetel ke true, task juga akan me-render versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Kolom thumbnail_url yang sudah ada tidak berubah.

Returns

Properti result pada respons berisi id dari task perbaikan 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: body model_url melebihi 100 MB.
    • Task belum berhasil: task yang dirujuk masih pending, sedang berlangsung, atau gagal.
    • GLB hilang: task yang dirujuk tidak memiliki asset GLB untuk diperbaiki.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Penyebab umum:

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

    Task yang dirujuk tidak ada atau dimiliki oleh pengguna lain.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui kuota task tertunda atau batas laju 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

Mengambil Task Perbaiki Kemampuan Cetak

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID dari task perbaiki kemampuan cetak yang ingin diambil.

Returns

Repair Printability Task Object. Blok model_urls akan kosong hingga task mencapai status SUCCEEDED. Hanya field model_urls yang sesuai dengan format input yang akan terisi.

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

Hapus Tugas Perbaiki Kemampuan Cetak

Endpoint ini menghapus secara permanen tugas perbaiki kemampuan cetak beserta hasil keluarannya yang telah diperbaiki. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

  • Name
    id
    Type
    path
    Description

    ID dari tugas perbaiki kemampuan cetak yang akan dihapus.

Status Tugas

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

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

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

Returns

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

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 default-nya adalah 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Default-nya adalah 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 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=***",
      "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

Stream a Repair Printability Task

Endpoint ini melakukan streaming pembaruan secara real-time untuk tugas repair-printability menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas repair-printability yang akan di-stream.

Returns

Mengembalikan stream berisi Repair 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 tersebut belum terisi (null, [] atau {}) dan finished_at bernilai null. Blok model_urls hanya dikirim setelah tugas mencapai status 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

    Pengidentifikasi unik untuk tugas ini. Meskipun kami menggunakan k-sortable UUID untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Tipe dari tugas repair-printability. Nilainya adalah print-repair.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Progress dari tugas ini. Jika tugas belum dimulai, properti ini akan berupa 0. Setelah tugas berhasil, ini akan menjadi 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang mendahului.

    Nilai dari field 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 berupa 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan berupa 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 bernilai 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 field yang sesuai dengan format input yang akan terisi; field format lainnya berupa string kosong.

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk GLB yang telah diperbaiki. Terisi ketika input berupa GLB atau ketika input_task_id digunakan.

    • Name
      gltf
      Type
      string
      Description

      URL yang dapat diunduh untuk GLTF yang telah diperbaiki. Terisi ketika input berupa unggahan GLTF.

    • Name
      fbx
      Type
      string
      Description

      URL yang dapat diunduh untuk FBX yang telah diperbaiki. Terisi ketika input berupa unggahan FBX.

    • Name
      obj
      Type
      string
      Description

      URL yang dapat diunduh untuk OBJ yang telah diperbaiki. Terisi ketika input berupa unggahan OBJ.

    • Name
      stl
      Type
      string
      Description

      URL yang dapat diunduh untuk STL yang telah diperbaiki. Terisi ketika input berupa unggahan STL.

    • Name
      usdz
      Type
      string
      Description

      Dicadangkan untuk output USDZ. Selalu berupa string kosong untuk tugas repair-printability.

    • Name
      3mf
      Type
      string
      Description

      Dicadangkan untuk output 3MF. Selalu berupa string kosong untuk tugas repair-printability.

    • Name
      mtl
      Type
      string
      Description

      Dicadangkan untuk output MTL. Selalu berupa string kosong untuk tugas repair-printability.

  • 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 latar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, field ini akan dihilangkan.

  • Name
    texture_urls
    Type
    array
    Description

    Selalu berupa array kosong. Perbaikan hanya mempertahankan geometri input dan tidak melakukan pembuatan ulang tekstur.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang terpakai oleh tugas ini. 10 setelah tugas mencapai status 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
}