API Cetak Multiwarna

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

POST/openapi/v1/print/multi-color

Buat Tugas Cetak 3D Multi-Warna

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

Parameter

Hanya salah satu dari input_task_id atau model_url yang diperlukan. Jika keduanya disediakan, 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 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 keluaran.
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 foto-realistis. Menghasilkan file yang lebih besar.
- cartoon: Meratakan warna menjadi wilayah yang bersih dan seragam untuk tampilan bergaya. Menghasilkan file yang lebih kecil.

Mengembalikan

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

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: model_url atau input_task_id harus disediakan.
- 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.
- Gaya tidak valid: Nilai harus realistic atau cartoon.
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 melebihi batas laju Anda.

Permintaan

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

Respons

{
  "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.

Mengembalikan

Objek Tugas Cetak 3D.

Permintaan

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

Respon

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

Menghapus Tugas Cetak 3D Multi-Warna

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

Parameter Jalur

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

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Permintaan

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

Respon

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Daftar Tugas Cetak 3D Multi-Warna

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

Parameter

Atribut opsional

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai 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 mengurutkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar ter-paginasi dari Objek Tugas Cetak 3D.

Permintaan

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

Respon

[
  {
    "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 mengalirkan pembaruan waktu nyata 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-stream.

Mengembalikan

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

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

Permintaan

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

Aliran Respons

// 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
Pengenal unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas 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 format akan dihilangkan jika format tersebut tidak dihasilkan, bukan mengembalikan string kosong.
- Name
  3mf
  Type
  string
  Description
  URL yang dapat diunduh untuk file 3MF multi-warna.
Name
progress
Type
integer
Description
Progress dari tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang mendahului.
Nilai dari 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 menjadi 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit 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
}