Multi-Color Print API

Konversi model 3D ke format 3MF multiwarna untuk pencetakan 3D, dengan palet warna yang dapat dikonfigurasi hingga 16 warna.

POST/openapi/v1/print/multi-color

Membuat Tugas Pencetakan 3D Multi-Warna

Endpoint ini membuat tugas pencetakan 3D multi-warna baru. Tugas ini mengonversi model 3D menjadi file 3MF multi-warna yang cocok untuk pencetakan 3D.

Tugas berjalan di latar belakang. Untuk mengetahui berapa lama biasanya proses ini berlangsung, lihat Waktu Pemrosesan.

Parameter

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

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas yang berhasil untuk digunakan sebagai input. Jenis tugas yang didukung: Gambar ke 3D, Multi-Gambar ke 3D, Teks ke 3D, Remesh, dan Retexture. Tugas harus memiliki status SUCCEEDED.

Name
model_url
Type
string
Wajib
Description
URL yang dapat diakses secara publik dari model .glb atau .fbx, atau URL data: base64 dari GLB (data:model/gltf-binary;base64,...). File .fbx harus dikirim sebagai URL http atau https.
Ukuran file maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.
File yang lebih dari 100 MB dapat memiliki paling banyak 8.000.000 wajah. Wajah dihitung sebagai segitiga: sebuah quad dihitung sebagai 2, dan mesh yang digambar lebih dari sekali dihitung satu kali per salinan. Di atas 100 MB, file FBX harus berupa FBX biner 7.1 atau yang lebih baru, dan file GLB tidak boleh menggunakan kompresi Draco.

Name
max_colors
Type
integer
default 4
Description
Jumlah maksimum warna dalam palet output.
Rentang yang valid: 1 hingga 16.
Name
style
Type
string
default realistic
Description
Gaya warna visual dari file 3MF yang dihasilkan.
Nilai yang tersedia:
- realistic: Mengambil sampel warna langsung dari tekstur model untuk detail yang halus dan fotorealistik. Menghasilkan file yang lebih besar.
- cartoon: Meratakan warna menjadi area yang bersih dan seragam untuk tampilan bergaya. Menghasilkan file yang lebih kecil.
Input harus memiliki warna: realistic memerlukan satu tekstur warna dasar dengan koordinat UV pada setiap bagian mesh; cartoon juga menerima warna per-vertex. Model tanpa tekstur (putih) akan ditolak — lihat model_missing_texture.
Name
max_depth
Type
integer
default 4
Description
Kedalaman subdivisi yang digunakan untuk mengambil sampel warna tekstur ke mesh. Nilai yang lebih tinggi menangkap detail warna yang lebih halus dengan konsekuensi file yang lebih besar. Berlaku hanya untuk gaya realistic; diabaikan untuk cartoon.
Rentang yang valid: 3 hingga 6.
Name
printer_brand
Type
string
default bambu
Description
Merek printer yang preset slicer-nya ditulis ke dalam 3MF, sehingga file terbuka di slicer merek tersebut dengan printer, filamen, dan profil proses yang sesuai. Setiap merek menggunakan printer default-nya dengan nozzle 0,4 mm.
Nilai yang tersedia: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Hasil Pengembalian

Properti result dari respons berisi id dari tugas pencetakan 3D yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Salah satu dari model_url atau input_task_id harus disediakan.
- Format model tidak valid: model_url menunjuk ke file dengan ekstensi yang tidak didukung (hanya .glb dan .fbx yang didukung).
- URL tidak dapat dijangkau: model_url tidak dapat diunduh.
- File model terlalu besar: File model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
- Terlalu banyak wajah: File model_url berukuran lebih dari 100 MB dan memiliki lebih dari 8.000.000 wajah. Kurangi jumlah wajah, lalu kirim file tersebut lagi.
- FBX ASCII di atas 100 MB: File model_url adalah FBX ASCII yang berukuran lebih dari 100 MB. Kirim sebagai FBX biner atau GLB.
- File model tidak dapat dibaca: File model_url berukuran lebih dari 100 MB dan headernya tidak dapat dibaca, misalnya GLB yang dikompresi Draco, atau FBX biner yang lebih lama dari 7.1.
- Header model terlalu kompleks: File model_url berukuran lebih dari 100 MB dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file, lalu kirim lagi.
- Tugas input tidak valid: input_task_id harus merujuk pada tugas yang berhasil.
- max_colors tidak valid: Nilai harus antara 1 dan 16.
- style tidak valid: Nilai harus realistic atau cartoon.
- max_depth tidak valid: Nilai harus antara 3 dan 6.
- printer_brand tidak valid: Nilai harus salah satu dari merek yang terdaftar di atas.
- Tidak ada sumber warna: Model input tidak memiliki tekstur warna dasar (realistic memerlukan satu, dengan UV, pada setiap bagian mesh) dan tidak memiliki warna vertex (cartoon menerima keduanya). Beri tekstur pada model terlebih dahulu, atau gunakan cartoon untuk model dengan warna vertex. Unggahan .fbx diperiksa setelah tugas menormalkannya dan gagal dengan model_missing_texture sebagai gantinya.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak cukup untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju Anda.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "printer_brand": "creality"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/multi-color/:id

Mengambil Tugas Cetak 3D Multi-Warna

Endpoint ini mengambil tugas cetak 3D multi-warna berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID dari tugas cetak 3D yang akan diambil.

Hasil

Objek Tugas Cetak 3D.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

Hapus Tugas 3D Print Multi-Warna

Endpoint ini menghapus secara permanen tugas 3D print multi-warna, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID tugas 3D print multi-warna yang akan dihapus.

Status Tugas

Tugas yang masih berstatus PENDING akan dihapus dan kredit yang terpakai 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 diproses oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

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/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/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/multi-color

Daftar Tugas Cetak 3D Multi-Warna

Endpoint ini memungkinkan Anda mengambil daftar tugas cetak 3D multi-warna.

Parameter

Atribut opsional

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai dan default-nya 1.
Name
page_size
Type
integer
Description
Batas ukuran halaman. Defaultnya 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 The 3D Print Task Objects.

Request

GET

/openapi/v1/print/multi-color

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

Streaming Tugas Cetak 3D Multi-Warna

Endpoint ini melakukan streaming pembaruan secara real-time untuk tugas cetak 3D multi-warna menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas cetak 3D multi-warna yang akan di-streaming.

Hasil

Mengembalikan stream dari Objek Tugas Cetak 3D sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan kolom progress dan status yang diperlukan.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Objek Task Cetak 3D

Name
id
Type
string
Description
Pengenal unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara-k (k-sortable) untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis task Cetak 3D. Nilainya adalah print-multi-color.
Name
model_urls
Type
object
Description
URL yang dapat diunduh untuk file model 3D yang dihasilkan oleh Meshy. Properti untuk suatu format akan dihilangkan jika format tersebut tidak dihasilkan, alih-alih mengembalikan string kosong.
- Name
  3mf
  Type
  string
  Description
  URL yang dapat diunduh untuk file 3MF multi-warna.
Name
progress
Type
integer
Description
Progress dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilai ini akan menjadi 100.
Name
status
Type
string
Description
Status dari task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang mendahului.
Nilai dari kolom ini hanya bermakna jika status task adalah PENDING.
Name
created_at
Type
timestamp
Description
Stempel waktu saat task dibuat, dalam milidetik.
Name
started_at
Type
timestamp
Description
Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh task ini. Muncul ketika status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit akan dikembalikan jika gagal).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}