Multi-Color Print API

I-convert ang 3D model patungo sa multi-color 3MF file para sa 3D printing. Pumili ng palette na may hanggang 16 na kulay at isang slicer preset para sa brand ng iyong printer.

POST/openapi/v1/print/multi-color

Gumawa ng Multi-Color Print task

Gumagawa ng Multi-Color Print task, na nagko-convert ng 3D model papuntang multi-color na 3MF file para sa 3D printing. Tumatakbo ang task sa background. Para sa karaniwang tagal ng isang task, tingnan ang Processing times.

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

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Kailangan maliban kung ipapadala mo ang model_url. Ang ID ng task na ang model nito ang gusto mong i-print, halimbawa ng isang Image to 3D, Multi-Image to 3D, Text to 3D, Remesh, o Retexture task. Dapat ang task ay isang ginawa mo gamit ang API, at may status na SUCCEEDED.
Binabasa ng Multi-Color Print ang GLB file ng task, na maaaring may pinakamataas na 8,000,000 faces. Ang model na may mas maraming faces ay nagbabalik ng 400. Sa ganitong kaso, patakbuhin muna ang isang Remesh task dito, at ipadala ang ID ng Remesh task sa halip.

Name
model_url
Type
string
Kinakailangan
Description
Kailangan maliban kung ipapadala mo ang input_task_id. Ang model na ipi-print, bilang isang pampublikong URL o isang data URI. Kung ipapadala mo pareho, gagamitin ng Meshy ang input_task_id.
Ang isang http o https URL ay dapat tumuturo sa isang .glb o .fbx file na may pinakamataas na 400 MB. Ang isang data URI ay dapat may hawak na base64 GLB file na may pinakamataas na 100 MB. Gamitin ang data:model/gltf-binary;base64,. Ipadala ang isang .fbx file bilang isang http o https URL.
Ang isang file na mas mataas sa 100 MB ay dapat ding sumunod sa mga sumusunod na patakaran:
- Maaari itong magkaroon ng pinakamataas na 8,000,000 faces. Binibilang ng Meshy ang faces bilang triangles, kaya't ang isang quad ay nabibilang bilang 2, at ang isang mesh na iginuhit nang higit sa isang beses ay nabibilang nang isang beses bawat kopya.
- Ang isang FBX file ay dapat binary FBX 7.1 o mas bago.
- Ang isang GLB file ay hindi dapat gumamit ng Draco compression.

Name
max_colors
Type
integer
default 4
Description
Ang pinakamataas na bilang ng mga kulay sa output palette, mula 1 hanggang 16. Para gamitin ang default, huwag na itong isama sa halip na ipadala ang 0.
Name
style
Type
string
default realistic
Description
Ang color style ng 3MF file.
Mga magagamit na halaga:
- realistic: kumukuha ng sample ng mga kulay direkta mula sa texture ng model para sa pino, photo-realistic na detalye, at gumagawa ng mas malaking file.
- cartoon: pinapantay ang mga kulay sa malinis, pare-parehong mga rehiyon para sa isang stylized na hitsura, at gumagawa ng mas maliit na file.
Dapat may kulay ang model. Kailangan ng realistic ng iisang base color texture, na may UVs sa bawat mesh part, at tinatanggap din ng cartoon ang vertex colors. Tatanggihan ng Meshy ang isang walang-texture (puting) model. Tingnan ang model_missing_texture.
Name
max_depth
Type
integer
default 4
Description
Ang subdivision depth na ginagamit ng Meshy para kumuha ng sample ng mga kulay ng texture papunta sa mesh, mula 3 hanggang 6. Ang 0 ay pareho lang ng hindi ito isama. Ang mas mataas na halaga ay kumukuha ng mas pinong detalye ng kulay, at gumagawa ng mas malaking file. Ang realistic style lamang ang gumagamit nito, at hindi ito pinapansin ng cartoon.
Name
printer_brand
Type
string
default bambu
Description
Ang printer brand na ang slicer preset nito ay isinusulat ng Meshy sa 3MF file. Ang file ay magbubukas pagkatapos sa slicer ng brand na iyon na may tumutugmang printer, filament, at process profile. Ginagamit ng preset ang default na printer ng brand, na may 0.4 mm na nozzle.
Mga magagamit na halaga:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Ang anumang ibang halaga ay nagbabalik ng 400.

Mga Ibinabalik

Ang result field ng tugon ay naghahawak ng ID ng bagong Multi-Color Print task.

Mga mode ng kabiguan

Name
400 - Bad Request
Description
Hindi matatakbo ang request. Sinasabi ng mensahe ng error kung aling problema ang nahanap nito. Halimbawa:
- Nawawalang parameter: Hindi ipinadala ang model_url ni input_task_id.
- Di-wastong format ng model: Ang model_url file ay hindi isang .glb o .fbx file.
- Hindi maabot na URL: Hindi ma-download ng Meshy ang model_url file.
- Masyadong malaki ang model file: Ang model_url file ay mahigit sa 400 MB mula sa isang http o https URL, o mahigit sa 100 MB bilang isang data URI.
- Masyadong maraming faces: Ang model_url file ay mahigit sa 100 MB at may mahigit sa 8,000,000 faces. Bawasan ang bilang ng faces, pagkatapos ipadala ulit ang file.
- ASCII FBX na mahigit sa 100 MB: Ang model_url file ay isang ASCII FBX na mahigit sa 100 MB. Ipadala ito bilang binary FBX o GLB.
- Hindi mabasang model file: Ang model_url file ay mahigit sa 100 MB, at hindi mabasa ng Meshy ang header nito. Halimbawa, ito ay isang Draco-compressed GLB, o isang binary FBX na mas luma sa 7.1.
- Masyadong kumplikado ang header ng model: Ang model_url file ay mahigit sa 100 MB, at ang header nito ay may masyadong maraming meshes, nodes, o records na susuriin. Bawasan ang bilang ng mga object sa file, pagkatapos ipadala ito ulit.
- Di-wastong input task: Ang input_task_id ay hindi isang matagumpay na task.
- Masyadong maraming faces sa input task: Ang input_task_id model ay may mahigit sa 8,000,000 faces. Patakbuhin ang isang Remesh task dito, pagkatapos ipadala ang ID ng Remesh task sa halip.
- Di-wastong max_colors: Ang max_colors ay negatibo o mahigit sa 16.
- Di-wastong style: Ang style ay hindi realistic o cartoon.
- Di-wastong max_depth: Ang max_depth ay wala sa saklaw na 3 hanggang 6, at hindi 0.
- Di-wastong printer_brand: Ang printer_brand ay hindi isa sa mga available na halaga nito.
- Walang pinagmumulan ng kulay: Kulang sa model ang kulay na kailangan ng style. Kailangan ng realistic ng iisang base color texture, na may UVs, sa bawat mesh part. Tinatanggap ng cartoon ang base color texture o vertex colors. I-texture muna ang model, o gamitin ang cartoon para sa isang model na may vertex colors. Sinusuri lamang ng Meshy ang isang .fbx upload pagkatapos i-normalize ng task ito, kaya nabibigo ang task na may model_missing_texture sa halip.
Ayusin ang request, pagkatapos ipadala ito ulit. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi wasto ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Kulang na credits: Ang account ay walang sapat na credits para sa task na ito, o naabot ng account ang isang limitasyon ng credit. Suriin ang iyong credit balance, pagkatapos subukan ulit.
- Libreng plano: Ang paggawa ng task ay nangangailangan ng isang bayad na plano. I-upgrade ang iyong plano sa iyong subscription settings, pagkatapos subukan ulit.
Name
403 - Forbidden
Description
Ang input_task_id ay isang bas-relief model, na hindi kayang i-print ng endpoint na ito. Ang mensahe ay This model type does not support this operation. Magpadala ng ibang model.
Name
404 - Not Found
Description
Ang input_task_id ay hindi tumutugma sa alinman sa iyong mga task. Suriin ang task ID, pagkatapos ipadala ulit ang request.
Name
429 - Too Many Requests
Description
Lumampas ka sa iyong rate limit. Maghintay, pagkatapos subukan ulit. Tingnan ang Rate limits.

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

Kumuha ng Multi-Color Print task

Ibinabalik ang isang Multi-Color Print task ayon sa kanyang ID.

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
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa sagot ng create.

Ibinabalik

Ang Multi-Color Print task object.

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

Mag-delete ng Multi-Color Print task

Permanenteng binubura ang isang Multi-Color Print task, kasama ang mga model at data nito. Hindi mo na maibabalik ang pag-delete.

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

Path parameters

Name
id
Type
path
Description
Ang ID ng task na ide-delete.

Status ng task

Kapag nag-delete ka ng PENDING na task, ibabalik ang credits na nagamit noong ginawa mo ito.

Hindi maaaring i-delete ang isang IN_PROGRESS na task. Ibabalik ng request ang 409 Conflict, at magpapatuloy pa rin ang pagtakbo ng task. Hindi nire-refund ng Meshy ang isang task na nasimulan na, kaya kung ide-delete mo ito, mawawalan ka ng parehong credits at resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

Ang pag-delete ng task na nasa final status (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng mga credits nito.

Mga ibinabalik na halaga

200 OK kapag na-delete na ang task, o 409 Conflict kapag ang task ay IN_PROGRESS.

GET/openapi/v1/print/multi-color

Ilista ang mga Multi-Color Print na gawain

Nagbabalik ng listahan ng iyong mga Multi-Color Print na gawain.

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

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Ang numero ng pahinang ibabalik. Ang mga numero ng pahina ay nagsisimula sa 1.
Name
page_size
Type
integer
default 10
Description
Ang bilang ng mga gawain bawat pahina, hanggang 100.
Name
sort_by
Type
string
Description
Ang pagkakasunod-sunod ng pag-uuri.
Mga available na halaga:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Ibinabalik

Isang paginated na listahan ng mga Multi-Color Print task object.

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

I-stream ang isang Multi-Color Print task

Nagsa-stream ng mga update ng isang Multi-Color Print task bilang 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
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Isang stream ng Multi-Color Print task objects bilang Server-Sent Events.

Bawat event ay may hawak na kumpletong task object, sa parehong anyo na ibinabalik ng Get endpoint. Habang ang task ay PENDING o IN_PROGRESS, wala pang mga value ang mga result field nito.

Ang Multi-Color Print task object

Ang isang Multi-Color Print task object ay naglalarawan ng isang pag-convert ng 3D model patungo sa multi-color 3MF file. Nilalaman nito ang status, ang progress, at ang 3MF file kapag nagtagumpay ang task.

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
Ang task ID. Ituring itong isang opaque string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging print-multi-color.
Name
model_urls
Type
object
Description
Mga download URL para sa na-print na model, isa para sa bawat format ng file. Ang isang format na hindi ginawa ng task ay walang key, sa halip na isang blangkong string.
- Name
  3mf
  Type
  string
  Description
  Ang multi-color 3MF file.
Name
progress
Type
integer
Description
Kung gaano karami ang natapos sa task, bilang porsyento. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, o CANCELED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nasa unahan ng task na ito sa pila. Makabuluhan lamang ang value na ito habang PENDING ang task.
Name
created_at
Type
timestamp
Description
Oras na nilikha ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras na nagsimula ang task, sa Unix milliseconds. Ito ay 0 hanggang magsimula ang task.
Name
finished_at
Type
timestamp
Description
Oras na natapos ang task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
expires_at
Type
timestamp
Description
Oras na mag-eexpire ang resulta ng task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
task_error
Type
object
Description
Ang mga detalye ng error kapag nabigo ang task. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task. Naroroon kapag ang status ay PENDING, IN_PROGRESS, o SUCCEEDED. Ito ay 0 para sa isang FAILED na task, dahil ibinabalik ni Meshy ang credits kapag nabigo ang isang task.