API Cetak Multiwarna

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

POST/openapi/v1/print/multi-color

Buat Tugas Pencetakan 3D Multiwarna

endpoint ini membuat tugas pencetakan 3D multiwarna baru. Tugas ini mengonversi model 3D menjadi file 3MF multiwarna yang cocok untuk pencetakan 3D.

Parameter

Hanya salah satu dari input_task_id atau model_url yang diperlukan. 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 atau Data URI dari model 3D. Saat ini kami mendukung format .glb dan .fbx.

Name
max_colors
Type
integer
default 4
Description
Jumlah maksimum warna dalam palet output.
Rentang valid: 1 hingga 16.
Name
max_depth
Type
integer
default 4
Description
Kedalaman quadtree untuk presisi warna. Nilai yang lebih tinggi menghasilkan batas warna yang lebih halus tetapi meningkatkan ukuran file.
Rentang valid: 3 hingga 6.

Mengembalikan

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 diberikan.
- Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung (hanya .glb dan .fbx yang didukung).
- URL tidak dapat dijangkau: model_url tidak dapat diunduh.
- Tugas input tidak valid: input_task_id harus merujuk ke tugas yang berhasil.
- max_colors tidak valid: Nilai harus antara 1 dan 16.
- max_depth tidak valid: Nilai harus antara 3 dan 6.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju Anda.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
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,
    "max_depth": 5
  }'

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 tugas cetak 3D yang akan diambil.

Mengembalikan

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 Cetak 3D Multi-Warna

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

Parameter Path

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

Pengembalian

Mengembalikan 200 OK jika berhasil.

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

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Cantumkan 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 dari 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 diurutkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menaik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menurun.

Pengembalian

Mengembalikan daftar terpaginasi dari Objek Tugas Cetak 3D.

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 real-time untuk tugas cetak 3D multi-warna menggunakan Server-Sent Events (SSE).

Parameter

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

Mengembalikan

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

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan bidang 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 Tugas Cetak 3D

Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID k-sortable untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id.
Name
type
Type
string
Description
Jenis tugas Cetak 3D. Nilainya adalah print-multi-color.
Name
model_urls
Type
object
Description
URL yang dapat diunduh ke 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 ke file 3MF multiwarna.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang mendahului.
Nilai bidang 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 bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 0.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada saat status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat 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
}