API Cetakan Pelbagai Warna

Tukar model 3D kepada fail 3MF pelbagai warna untuk pencetakan 3D. Pilih palet sehingga 16 warna dan praset slicer untuk jenama pencetak anda.

POST/openapi/v1/print/multi-color

Cipta tugas Cetakan Pelbagai Warna

Mencipta tugas Cetakan Pelbagai Warna, yang menukar model 3D kepada fail 3MF pelbagai warna untuk pencetakan 3D. Tugas berjalan di latar belakang. Untuk tempoh biasa yang diambil oleh sesuatu tugas, lihat Masa pemprosesan.

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
Diperlukan
Description
Diperlukan melainkan anda menghantar model_url. ID tugas yang modelnya ingin anda cetak, contohnya tugas Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D, Remesh, atau Retekstur. Tugas itu mesti yang anda cipta menggunakan API, dan mempunyai status SUCCEEDED.
Cetakan Pelbagai Warna membaca fail GLB tugas tersebut, yang boleh mempunyai paling banyak 8,000,000 segi tiga (faces). Model dengan lebih banyak segi tiga akan mengembalikan 400. Dalam kes itu, jalankan tugas Remesh terlebih dahulu, dan hantar ID tugas Remesh itu sebagai gantinya.

Name
model_url
Type
string
Diperlukan
Description
Diperlukan melainkan anda menghantar input_task_id. Model untuk dicetak, sebagai URL awam atau data URI. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.
URL http atau https mesti menuju kepada fail .glb atau .fbx bersaiz paling banyak 400 MB. Data URI mesti mengandungi fail GLB base64 bersaiz paling banyak 100 MB. Gunakan data:model/gltf-binary;base64,. Hantar fail .fbx sebagai URL http atau https.
Fail yang melebihi 100 MB juga mesti mematuhi peraturan berikut:
- Ia boleh mempunyai paling banyak 8,000,000 segi tiga (faces). Meshy mengira segi tiga sebagai triangle, jadi segi empat (quad) dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan.
- Fail FBX mesti FBX binari versi 7.1 atau lebih baharu.
- Fail GLB tidak boleh menggunakan pemampatan Draco.

Name
max_colors
Type
integer
lalai 4
Description
Bilangan maksimum warna dalam palet output, dari 1 hingga 16. Untuk menggunakan nilai lalai, biarkan ia dihilangkan dan bukannya menghantar 0.
Name
style
Type
string
lalai realistic
Description
Gaya warna fail 3MF.
Nilai yang tersedia:
- realistic: mengambil sampel warna terus daripada tekstur model untuk perincian yang halus dan realistik seperti foto, serta menghasilkan fail yang lebih besar.
- cartoon: meratakan warna kepada kawasan yang bersih dan seragam untuk rupa bergaya, serta menghasilkan fail yang lebih kecil.
Model mesti mempunyai warna. realistic memerlukan satu tekstur warna asas, dengan UV pada setiap bahagian jejaring, manakala cartoon juga menerima warna bucu (vertex colors). Meshy menolak model yang tidak bertekstur (putih). Lihat model_missing_texture.
Name
max_depth
Type
integer
lalai 4
Description
Kedalaman subdivisi yang digunakan Meshy untuk mengambil sampel warna tekstur ke atas jejaring, dari 3 hingga 6. 0 adalah sama seperti membiarkannya dihilangkan. Nilai yang lebih tinggi menangkap perincian warna yang lebih halus, dan menghasilkan fail yang lebih besar. Hanya gaya realistic yang menggunakannya, dan cartoon mengabaikannya.
Name
printer_brand
Type
string
lalai bambu
Description
Jenama pencetak yang pratetap slicer-nya ditulis oleh Meshy ke dalam fail 3MF. Fail itu kemudian dibuka dalam slicer jenama tersebut dengan profil pencetak, filamen, dan proses yang sepadan. Pratetap menggunakan pencetak lalai jenama tersebut, dengan nozel 0.4 mm.
Nilai yang tersedia:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Nilai lain akan mengembalikan 400.

Pulangan

Medan result bagi respons mengandungi ID tugas Cetakan Pelbagai Warna yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:
- Parameter hilang: Tiada model_url mahupun input_task_id dihantar.
- Format model tidak sah: Fail model_url bukan fail .glb atau .fbx.
- URL tidak dapat dicapai: Meshy tidak dapat memuat turun fail model_url.
- Fail model terlalu besar: Fail model_url melebihi 400 MB daripada URL http atau https, atau melebihi 100 MB sebagai data URI.
- Terlalu banyak segi tiga: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 8,000,000 segi tiga. Kurangkan bilangan segi tiga, kemudian hantar semula fail itu.
- FBX ASCII melebihi 100 MB: Fail model_url ialah FBX ASCII yang melebihi 100 MB. Hantar ia sebagai FBX binari atau GLB.
- Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB, dan Meshy tidak dapat membaca pengepalanya. Contohnya, ia adalah GLB yang dimampatkan menggunakan 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 itu, kemudian hantar semula.
- Tugas input tidak sah: input_task_id bukan tugas yang berjaya.
- Terlalu banyak segi tiga dalam tugas input: Model input_task_id mempunyai lebih daripada 8,000,000 segi tiga. Jalankan tugas Remesh ke atasnya, kemudian hantar ID tugas Remesh itu sebagai gantinya.
- max_colors tidak sah: max_colors adalah negatif atau melebihi 16.
- style tidak sah: style bukan realistic atau cartoon.
- max_depth tidak sah: max_depth berada di luar julat 3 hingga 6, dan bukan 0.
- printer_brand tidak sah: printer_brand bukan salah satu daripada nilai yang tersedia.
- Tiada sumber warna: Model tidak mempunyai warna yang diperlukan oleh style. realistic memerlukan satu tekstur warna asas, dengan UV, pada setiap bahagian jejaring. cartoon menerima tekstur warna asas atau warna bucu. Beri tekstur pada model terlebih dahulu, atau gunakan cartoon untuk model yang mempunyai warna bucu. Meshy hanya menyemak muat naik .fbx selepas tugas menormalkannya, jadi tugas itu gagal dengan model_missing_texture sebagai gantinya.
Baiki permintaan itu, kemudian hantar semula. Lihat Ralat.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Contohnya:
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
input_task_id adalah model bas-relief, yang tidak dapat dicetak oleh endpoint ini. Mesejnya ialah This model type does not support this operation. Hantar model yang berbeza.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugas anda. Semak ID tugas itu, kemudian hantar semula permintaan.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

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

Dapatkan tugas Cetakan Pelbagai Warna

Mengembalikan tugas Cetakan Pelbagai Warna mengikut 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 tugas daripada respons penciptaan.

Pulangan

Objek tugas Cetakan Pelbagai Warna.

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

Padam tugas Cetakan Pelbagai Warna

Memadam tugas Cetakan Pelbagai Warna secara kekal, termasuk model dan datanya. Anda tidak boleh membuat asal pemadaman.

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 laluan

Name
id
Type
path
Description
ID tugas yang hendak dipadam.

Status tugas

Memadam tugas PENDING akan memulangkan semula kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut akan terus berjalan. Meshy tidak memulangkan semula kredit untuk tugas yang telah dimulakan, jadi memadamnya akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan memulangkan semula kreditnya.

Pulangan

200 OK apabila tugas berjaya dipadam, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

GET/openapi/v1/print/multi-color

Senaraikan tugas Cetakan Pelbagai Warna

Mengembalikan senarai tugas cetakan pelbagai warna 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
lalai 1
Description
Nombor halaman yang hendak dikembalikan. Nombor halaman bermula pada 1.
Name
page_size
Type
integer
lalai 10
Description
Bilangan tugas setiap halaman, sehingga 100.
Name
sort_by
Type
string
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baharu dahulu

Mengembalikan

Senarai bernombor halaman bagi objek tugas cetakan pelbagai warna.

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

Alirkan tugas Cetakan Pelbagai Warna

Mengalirkan kemas kini tugas Cetakan Pelbagai Warna 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 daripada respons create.

Nilai Pulangan

Aliran objek tugas Cetakan Pelbagai Warna sebagai Server-Sent Events.

Setiap event mengandungi objek tugas yang lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan hasilnya belum lagi mempunyai nilai.

Objek tugas Cetakan Pelbagai Warna

Objek tugas Cetakan Pelbagai Warna menerangkan satu penukaran model 3D kepada fail 3MF pelbagai warna. Ia menyimpan status, progress, dan fail 3MF apabila tugas berjaya.

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. Anggap ia sebagai rentetan legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa print-multi-color.
Name
model_urls
Type
object
Description
URL muat turun untuk model yang dicetak, satu bagi setiap format fail. Format yang tidak dijana oleh tugas tidak mempunyai kunci, bukannya rentetan kosong.
- Name
  3mf
  Type
  string
  Description
  Fail 3MF pelbagai warna.
Name
progress
Type
integer
Description
Berapa banyak tugas telah selesai, sebagai peratusan. Nilainya 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Nilainya 0 sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas. Hadir apabila status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk tugas FAILED, kerana Meshy memulangkan semula kredit apabila tugas gagal.