API Cetak Multiwarna

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

Endpoint ini membuat task cetak 3D multi-warna baru. Task 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 wajib diisi. Jika keduanya diberikan, input_task_id akan diprioritaskan.

  • 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 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 wilayah yang bersih dan seragam untuk tampilan bergaya. Menghasilkan file yang lebih kecil.

    Input harus membawa 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.

Hasil

Properti result pada respons berisi id dari task cetak 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.
    • Task input tidak valid: input_task_id harus mengacu pada task yang berhasil.
    • max_colors tidak valid: Nilai harus antara 1 dan 16.
    • style tidak valid: Nilai harus realistic atau cartoon.
    • 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 task menormalkannya dan akan 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 menjalankan task 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
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/multi-color/:id

Mengambil Task Cetak 3D Multi-Warna

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID dari task cetak 3D yang ingin diambil.

Hasil

Objek Task 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

Menghapus Tugas Cetak 3D Multi-Warna

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

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID tugas cetak 3D multi-warna yang akan dihapus.

Status Tugas

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

Tugas yang sudah 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 mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus.

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

Return

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

List Multi-Color 3D Print Tasks

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 defaultnya adalah 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Defaultnya 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 (ascending).
    • -created_at: Urutkan berdasarkan waktu pembuatan secara menurun (descending).

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

Melakukan 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 Pengembalian

Mengembalikan aliran The 3D Print Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, aliran 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 3D Print

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi 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

    Tipe dari task 3D Print. 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 bernilai 0. Setelah task berhasil, nilainya 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 field 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 bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini 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 terpakai oleh task ini. Muncul saat status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika terjadi kegagalan).

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
}