lowpoly dihentikan pada 30 Okt 2026. Ganti model sebelum tanggal-tanggal ini agar permintaan tidak error. Lihat semua penghentian

API Cetak Multiwarna

Konversi model 3D menjadi file 3MF multiwarna untuk pencetakan 3D. Pilih palet hingga 16 warna dan preset slicer untuk merek printer Anda.

POST/openapi/v1/print/multi-color

Buat tugas Multi-Color Print

Membuat tugas Multi-Color Print, yang mengonversi model 3D menjadi file 3MF multiwarna untuk pencetakan 3D. Tugas berjalan di latar belakang. Untuk mengetahui berapa lama sebuah tugas biasanya berlangsung, lihat Waktu pemrosesan.

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

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    Wajib kecuali Anda mengirim model_url. ID tugas yang modelnya ingin Anda cetak, misalnya tugas Gambar ke 3D, Multi-Gambar ke 3D, Teks ke 3D, Remesh, atau Retexture. Tugas tersebut harus yang Anda buat dengan API, dan memiliki status SUCCEEDED.

    Multi-Color Print membaca file GLB tugas tersebut, yang boleh memiliki paling banyak 8.000.000 wajah (face). Model dengan jumlah wajah lebih banyak akan mengembalikan 400. Dalam kasus itu, jalankan dulu tugas Remesh padanya, lalu kirim ID tugas Remesh tersebut sebagai gantinya.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Wajib kecuali Anda mengirim input_task_id. Model yang akan dicetak, berupa URL publik atau data URI. Jika Anda mengirim keduanya, Meshy menggunakan input_task_id.

    URL http atau https harus mengarah ke file .glb atau .fbx berukuran paling besar 400 MB. Data URI harus berisi file GLB base64 berukuran paling besar 100 MB. Gunakan data:model/gltf-binary;base64,. Kirim file .fbx sebagai URL http atau https.

    File yang lebih besar dari 100 MB juga harus mengikuti aturan berikut:

    • Paling banyak memiliki 8.000.000 wajah. Meshy menghitung wajah sebagai segitiga, jadi satu quad dihitung sebagai 2, dan mesh yang digambar lebih dari sekali dihitung sekali per salinan.
    • File FBX harus berupa FBX biner 7.1 atau yang lebih baru.
    • File GLB tidak boleh menggunakan kompresi Draco.
  • Name
    max_colors
    Type
    integer
    default 4
    Description

    Jumlah maksimum warna dalam palet keluaran, dari 1 hingga 16. Untuk menggunakan nilai default, jangan sertakan parameter ini alih-alih mengirim 0.

  • Name
    style
    Type
    string
    default realistic
    Description

    Gaya warna dari file 3MF.

    Nilai yang tersedia:

    • realistic: mengambil sampel warna langsung dari tekstur model untuk detail yang halus dan fotorealistis, serta menghasilkan file yang lebih besar.
    • cartoon: meratakan warna menjadi area yang bersih dan seragam untuk tampilan bergaya, serta menghasilkan file yang lebih kecil.

    Model harus memiliki warna. realistic membutuhkan satu tekstur warna dasar, dengan UV pada setiap bagian mesh, dan cartoon juga menerima warna vertex. Meshy menolak model yang tidak bertekstur (putih). Lihat model_missing_texture.

  • Name
    max_depth
    Type
    integer
    default 4
    Description

    Kedalaman subdivisi yang digunakan Meshy untuk mengambil sampel warna tekstur ke mesh, dari 3 hingga 6. 0 sama dengan tidak menyertakannya. Nilai yang lebih tinggi menangkap detail warna yang lebih halus, dan menghasilkan file yang lebih besar. Hanya gaya realistic yang menggunakannya, sedangkan cartoon mengabaikannya.

  • Name
    printer_brand
    Type
    string
    default bambu
    Description

    Merek printer yang preset slicer-nya ditulis Meshy ke dalam file 3MF. File tersebut kemudian terbuka di slicer merek tersebut dengan printer, filamen, dan profil proses yang sesuai. Preset menggunakan printer default merek tersebut, dengan nozzle 0,4 mm.

    Nilai yang tersedia:

    • bambu
    • anycubic
    • creality
    • elegoo
    • flashforge
    • prusa
    • qidi
    • snapmaker
    • ankermake

    Nilai lain akan mengembalikan 400.

Hasil

Kolom result pada respons berisi ID dari tugas Multi-Color Print yang baru.

Mode kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Pesan kesalahan menyebutkan masalah yang ditemukan. Misalnya:

    • Parameter hilang: Baik model_url maupun input_task_id tidak dikirim.
    • Format model tidak valid: File model_url bukan file .glb atau .fbx.
    • URL tidak dapat dijangkau: Meshy tidak dapat mengunduh file model_url.
    • File model terlalu besar: File model_url berukuran lebih dari 400 MB dari URL http atau https, atau lebih dari 100 MB sebagai data URI.
    • 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 lebih dari 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 Meshy tidak dapat membaca headernya. Misalnya, file tersebut adalah GLB terkompresi 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 bukan tugas yang berhasil.
    • Terlalu banyak wajah pada tugas input: Model input_task_id memiliki lebih dari 8.000.000 wajah. Jalankan tugas Remesh padanya, lalu kirim ID tugas Remesh tersebut sebagai gantinya.
    • max_colors tidak valid: max_colors bernilai negatif atau lebih dari 16.
    • style tidak valid: style bukan realistic atau cartoon.
    • max_depth tidak valid: max_depth berada di luar rentang 3 hingga 6, dan bukan 0.
    • printer_brand tidak valid: printer_brand bukan salah satu dari nilai yang tersedia.
    • Tidak ada sumber warna: Model tidak memiliki warna yang dibutuhkan oleh style. realistic membutuhkan satu tekstur warna dasar, dengan UV, pada setiap bagian mesh. cartoon menerima tekstur warna dasar atau warna vertex. Beri tekstur pada model terlebih dahulu, atau gunakan cartoon untuk model dengan warna vertex. Meshy hanya memeriksa unggahan .fbx setelah tugas menormalkannya, sehingga tugas gagal dengan model_missing_texture sebagai gantinya.

    Perbaiki permintaan, lalu kirim lagi. Lihat Kesalahan.

  • Name
    401 - Unauthorized
    Description

    Kunci API tidak ada atau tidak valid. Periksa header Authorization.

  • Name
    402 - Payment Required
    Description

    Misalnya:

    • Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
    • Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan Anda, lalu coba lagi.
  • Name
    403 - Forbidden
    Description

    input_task_id adalah model bas-relief, yang tidak dapat dicetak oleh endpoint ini. Pesannya adalah This model type does not support this operation. Kirim model yang berbeda.

  • Name
    404 - Not Found
    Description

    input_task_id tidak cocok dengan tugas Anda mana pun. Periksa ID tugas, lalu kirim permintaan lagi.

  • Name
    429 - Too Many Requests
    Description

    Anda melebihi batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Mendapatkan task Multi-Color Print

Mengembalikan task Multi-Color Print berdasarkan ID-nya.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID task dari respons pembuatan.

Returns

Objek task Multi-Color Print.

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

Hapus tugas Cetak Multiwarna

Menghapus tugas Cetak Multiwarna secara permanen, termasuk model dan datanya. Anda tidak dapat membatalkan penghapusan ini.

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

Parameter path

  • Name
    id
    Type
    path
    Description

    ID tugas yang akan dihapus.

Status tugas

Menghapus tugas PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Tugas IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut tetap berjalan. Meshy tidak mengembalikan kredit untuk tugas yang sudah dimulai, jadi menghapusnya akan membuat Anda rugi baik kredit maupun hasilnya. Tunggu hingga tugas mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Menghapus tugas pada status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak mengembalikan kreditnya.

Returns

200 OK ketika tugas berhasil dihapus, atau 409 Conflict ketika tugas berstatus IN_PROGRESS.

GET/openapi/v1/print/multi-color

Daftar tugas Cetak Multiwarna

Mengembalikan daftar tugas Cetak Multiwarna Anda.

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,
    "expires_at": 1700259201000,
    "task_error": null,
  "consumed_credits": 10
  }
]

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman yang akan dikembalikan. Nomor halaman dimulai dari 1.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Jumlah tugas per halaman, hingga 100.

  • Name
    sort_by
    Type
    string
    Description

    Urutan pengurutan.

    Nilai yang tersedia:

    • +created_at: terlama lebih dulu
    • -created_at: terbaru lebih dulu

Returns

Daftar berhalaman dari objek tugas Cetak Multiwarna.

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

Stream Tugas Multi-Color Print

Melakukan streaming pembaruan tugas Multi-Color Print sebagai Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas dari respons pembuatan.

Returns

Sebuah stream objek tugas Multi-Color Print sebagai Server-Sent Events.

Setiap event berisi objek tugas lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom hasilnya belum memiliki nilai.

Objek tugas Cetak Multiwarna

Objek tugas Cetak Multiwarna menjelaskan satu konversi model 3D menjadi file 3MF multiwarna. Objek ini menyimpan status, progress, dan file 3MF saat tugas berhasil.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}
  • Name
    id
    Type
    string
    Description

    ID tugas. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, selalu print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    URL unduhan untuk model yang dicetak, satu per format file. Format yang tidak dihasilkan oleh tugas tidak memiliki kunci, bukan string kosong.

    • Name
      3mf
      Type
      string
      Description

      File 3MF multiwarna.

  • Name
    progress
    Type
    integer
    Description

    Seberapa banyak tugas telah selesai, dalam persentase. Nilainya 0 hingga tugas dimulai dan 100 saat berhasil.

  • Name
    status
    Type
    string
    Description

    Status tugas, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang berada di depan tugas ini dalam antrean. Nilai ini hanya bermakna selama tugas berstatus PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Waktu tugas dibuat, dalam milidetik Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Waktu tugas dimulai, dalam milidetik Unix. Nilainya 0 hingga tugas dimulai.

  • Name
    finished_at
    Type
    timestamp
    Description

    Waktu tugas selesai, dalam milidetik Unix. Nilainya 0 hingga tugas selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 0 hingga tugas selesai.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan saat tugas gagal. Lihat Kesalahan.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan oleh tugas. Ada saat status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk tugas FAILED, karena Meshy mengembalikan kredit saat tugas gagal.