API Cetakan Pelbagai Warna

Tukar model 3D kepada format 3MF pelbagai warna untuk pencetakan 3D, dengan palet warna yang boleh dikonfigurasi sehingga 16 warna.

POST/openapi/v1/print/multi-color

Cipta Tugas Cetakan 3D Berbilang Warna

Endpoint ini mencipta tugas cetakan 3D berbilang warna yang baharu. Tugas ini menukar model 3D kepada fail 3MF berbilang warna yang sesuai untuk pencetakan 3D.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diperlukan, lihat Masa Pemprosesan.

Parameter

Hanya salah satu daripada input_task_id atau model_url yang diperlukan. Jika kedua-duanya disediakan, input_task_id diberi keutamaan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas yang berjaya untuk digunakan sebagai input. Jenis tugas yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D, Remesh, dan Retekstur. Tugas itu mesti mempunyai status SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
URL yang boleh diakses secara awam bagi model .glb atau .fbx, atau URL data: base64 bagi GLB (data:model/gltf-binary;base64,...). Fail .fbx mesti dihantar sebagai URL http atau https.
Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.
Fail yang melebihi 100 MB boleh mempunyai sebanyak-banyaknya 8,000,000 segi. Segi dikira sebagai segi tiga: segi empat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan. Melebihi 100 MB, fail FBX mestilah FBX binari 7.1 atau lebih baharu, dan fail GLB tidak boleh menggunakan mampatan Draco.

Name
max_colors
Type
integer
lalai 4
Description
Bilangan maksimum warna dalam palet output.
Julat yang sah: 1 hingga 16.
Name
style
Type
string
lalai realistic
Description
Gaya warna visual bagi fail 3MF yang dijana.
Nilai yang tersedia:
- realistic: Mengambil sampel warna terus daripada tekstur model untuk perincian yang halus dan sehalus foto. Menghasilkan fail yang lebih besar.
- cartoon: Meratakan warna kepada kawasan yang bersih dan seragam untuk rupa yang bergaya. Menghasilkan fail yang lebih kecil.
Input mesti membawa warna: realistic memerlukan satu tekstur warna asas dengan koordinat UV pada setiap bahagian jejaring; cartoon juga menerima warna setiap bucu. Model tanpa tekstur (putih) akan ditolak — lihat model_missing_texture.
Name
max_depth
Type
integer
lalai 4
Description
Kedalaman subbahagian yang digunakan untuk mengambil sampel warna tekstur ke atas jejaring. Nilai yang lebih tinggi menangkap perincian warna yang lebih halus dengan kos fail yang lebih besar. Hanya digunakan untuk gaya realistic; diabaikan untuk cartoon.
Julat yang sah: 3 hingga 6.
Name
printer_brand
Type
string
lalai bambu
Description
Jenama pencetak yang prasetan slicernya ditulis ke dalam 3MF, supaya fail dibuka dalam slicer jenama tersebut dengan profil pencetak, filamen dan proses yang sepadan. Setiap jenama menggunakan pencetak lalainya dengan nozel 0.4 mm.
Nilai yang tersedia: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Pulangan

Sifat result bagi respons mengandungi id bagi tugas cetakan 3D yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
- Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong (hanya .glb dan .fbx disokong).
- URL tidak boleh dicapai: model_url tidak dapat dimuat turun.
- Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
- Terlalu banyak segi: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 8,000,000 segi. Kurangkan bilangan segi, kemudian hantar semula fail tersebut.
- FBX ASCII melebihi 100 MB: Fail model_url adalah FBX ASCII yang melebihi 100 MB. Hantar sebagai FBX binari atau GLB.
- Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB dan pengepalanya tidak dapat dibaca, contohnya GLB yang dimampatkan dengan Draco, atau FBX binari yang lebih lama daripada 7.1.
- Pengepala model terlalu kompleks: Fail model_url melebihi 100 MB dan pengepalanya mempunyai terlalu banyak jejaring, nod atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.
- Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya.
- max_colors tidak sah: Nilai mesti antara 1 dan 16.
- style tidak sah: Nilai mesti realistic atau cartoon.
- max_depth tidak sah: Nilai mesti antara 3 dan 6.
- printer_brand tidak sah: Nilai mesti salah satu daripada jenama yang disenaraikan di atas.
- Tiada sumber warna: Model input tidak mempunyai tekstur warna asas (realistic memerlukan satu, dengan UV, pada setiap bahagian jejaring) dan tiada warna bucu (cartoon menerima kedua-duanya). Teksturkan model dahulu, atau gunakan cartoon untuk model berwarna bucu. Muat naik .fbx disemak selepas tugas menormalkannya dan gagal dengan model_missing_texture sebaliknya.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar 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

Dapatkan Tugas Cetakan 3D Pelbagai Warna

endpoint ini mendapatkan semula tugas cetakan 3D pelbagai warna berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas cetakan 3D yang hendak didapatkan semula.

Pulangan

Objek Tugas Cetakan 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

Padam Tugas Cetakan 3D Pelbagai Warna

Endpoint ini memadam secara kekal tugas cetakan 3D pelbagai warna, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diundurkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas cetakan 3D pelbagai warna yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas tersebut akan terus berjalan. Kredit bagi tugas yang telah pun dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam status terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa pemulangan semula kredit.

Returns

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugas adalah 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

Senaraikan Tugasan Cetakan 3D Berbilang Warna

Endpoint ini membolehkan anda mendapatkan semula senarai tugasan cetakan 3D berbilang warna.

Parameter

Atribut pilihan

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan lalai kepada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Lalai kepada 10 item. Maksimum yang dibenarkan ialah 100 item.
Name
sort_by
Type
string
Description
Medan untuk disusun. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berhalaman bagi Objek Tugasan Cetakan 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

Strim Tugas Cetakan 3D Berbilang Warna

Endpoint ini menstrim kemas kini masa nyata untuk tugas cetakan 3D berbilang warna menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas cetakan 3D berbilang warna yang hendak distrim.

Nilai Pulangan

Mengembalikan strim Objek Tugas Cetakan 3D sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan mengandungi medan 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 Cetakan 3D

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun-k (k-sortable) untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Cetakan 3D. Nilainya ialah print-multi-color.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk fail model 3D yang dijana oleh Meshy. Sifat untuk sesuatu format akan ditinggalkan jika format tersebut tidak dijana, dan bukannya memulangkan rentetan kosong.
- Name
  3mf
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail 3MF pelbagai warna.
Name
progress
Type
integer
Description
Progress bagi tugas tersebut. Jika tugas belum bermula lagi, sifat ini akan menjadi 0. Sebaik sahaja tugas berjaya, nilai ini akan menjadi 100.
Name
status
Type
string
Description
Status tugas tersebut. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas tersebut dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas tersebut dimulakan, dalam milisaat. Jika tugas belum bermula lagi, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas tersebut selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi 0.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Memulangkan 0 untuk tugas FAILED (kredit dikembalikan apabila berlaku 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
}