Multi-Color Print API

I-convert ang mga 3D na modelo sa multi-color 3MF format para sa 3D printing, gamit ang isang naisasaayos na color palette na may hanggang 16 na kulay.

POST/openapi/v1/print/multi-color

Gumawa ng Multi-Color 3D Print Task

Ang endpoint na ito ay lumilikha ng bagong multi-color 3D print task. I-convert ng task ang isang 3D model patungo sa multi-color na 3MF file na angkop para sa 3D printing.

Mga Parameter

Isa lamang sa input_task_id o model_url ang kailangan. Kung parehong ibinigay, ang input_task_id ang mananaig.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang matagumpay na task na gagamitin bilang input. Mga sinusuportahang uri ng task: Image to 3D, Multi-Image to 3D, Text to 3D, Remesh, at Retexture. Dapat ang status ng task ay SUCCEEDED.

Name
model_url
Type
string
Kinakailangan
Description
Publicly accessible na URL o Data URI ng isang 3D model. Kasalukuyan naming sinusuportahan ang mga format na .glb at .fbx.

Name
max_colors
Type
integer
default 4
Description
Pinakamataas na bilang ng mga kulay sa output palette.
Valid na saklaw: 1 hanggang 16.
Name
style
Type
string
default realistic
Description
Visual na color style ng nabuong 3MF file.
Mga magagamit na halaga:
- realistic: Nagsa-sample ng mga kulay nang direkta mula sa texture ng model para sa pinong, photo-realistic na detalye. Nagbubunga ng mas malaking file.
- cartoon: Pinapatag ang mga kulay sa malinis, uniporme na mga rehiyon para sa stylized na hitsura. Nagbubunga ng mas maliit na file.
Dapat may kulay ang input: ang realistic ay nangangailangan ng iisang base color texture na may UV coordinates sa bawat bahagi ng mesh; tinatanggap din ng cartoon ang per-vertex colors. Tinatanggihan ang mga walang texture (puting) na mga model — tingnan ang model_missing_texture.
Name
max_depth
Type
integer
default 4
Description
Subdivision depth na ginagamit upang i-sample ang mga kulay ng texture papunta sa mesh. Ang mas mataas na halaga ay nakakakuha ng mas pinong detalye ng kulay sa kapalit ng mas malaking file. Naaangkop lamang sa realistic style; hindi pinapansin para sa cartoon.
Valid na saklaw: 3 hanggang 6.
Name
printer_brand
Type
string
default bambu
Description
Ang printer brand kung saan isinusulat ang slicer preset sa 3MF, kaya bubukas ang file sa slicer ng brand na iyon na may tumutugmang printer, filament, at process profile. Gumagamit ang bawat brand ng kanyang default printer na may 0.4 mm na nozzle.
Mga magagamit na halaga: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Mga Ibinabalik

Ang property na result ng response ay naglalaman ng id ng bagong likhang 3D print task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:
- Nawawalang parameter: Dapat ibigay ang alinman sa model_url o input_task_id.
- Hindi valid na format ng model: Tumuturo ang model_url sa isang file na may hindi suportadong extension (.glb at .fbx lamang ang sinusuportahan).
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Hindi valid na input task: Dapat tumukoy ang input_task_id sa isang matagumpay na task.
- Hindi valid na max_colors: Dapat ang halaga ay nasa pagitan ng 1 at 16.
- Hindi valid na style: Dapat ang halaga ay realistic o cartoon.
- Hindi valid na max_depth: Dapat ang halaga ay nasa pagitan ng 3 at 6.
- Hindi valid na printer_brand: Dapat ang halaga ay isa sa mga brand na nakalista sa itaas.
- Walang pinagmumulan ng kulay: Walang base color texture ang input model (kailangan ng realistic ng iisa, na may UVs, sa bawat bahagi ng mesh) at walang vertex colors (tinatanggap ng cartoon ang alinman). I-texture muna ang model, o gamitin ang cartoon para sa mga model na may vertex-colored. Ang mga .fbx upload ay sinusuri matapos i-normalize ng task ang mga ito at nabibigo nang may model_missing_texture sa halip.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Mangyaring suriin ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits upang maisagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalampasan mo na ang iyong rate limit.

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

I-retrieve ang Multi-Color 3D Print Task

Kinukuha ng endpoint na ito ang isang multi-color 3D print task gamit ang kanyang ID.

Mga Parameter

Name
id
Type
path
Description
Ang ID ng 3D print task na kukunin.

Ibinabalik

Ang 3D Print Task object.

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

Delete a Multi-Color 3D Print Task

Ang endpoint na ito ay permanenteng nagtatanggal ng multi-color 3D print task, kabilang ang lahat ng nauugnay na mga modelo at datos. Ang aksyong ito ay hindi na maibabalik.

Path Parameters

Name
id
Type
path
Description
Ang ID ng multi-color 3D print task na tatanggalin.

Task Status

Ang task na PENDING pa ay tinatanggal at ang mga credits na nagamit noong oras ng paggawa ay ibinabalik.

Ang task na IN_PROGRESS na ay hindi maaaring tanggalin: ang request ay tinatanggihan na may 409 Conflict at ang task ay patuloy na tumatakbo. Ang mga credits para sa isang task na nasimulan na ng worker ay hindi na maibabalik, kaya ang pagtanggal dito habang tumatakbo ay magiging sanhi ng pagkawala ng iyong mga credits pati na rin ng resulta. Hintayin itong umabot sa SUCCEEDED, FAILED o CANCELED, bago ito tanggalin.

Ang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay tinatanggal nang walang refund.

Returns

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay 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

Ilista ang Multi-Color 3D Print Tasks

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang listahan ng multi-color 3D print tasks.

Mga Parameter

Opsyonal na attributes

Name
page_num
Type
integer
Description
Numero ng pahina para sa pagination. Nagsisimula at default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa laki ng pahina. Default ay 10 na item. Ang pinakamataas na pinapayagan ay 100 na item.
Name
sort_by
Type
string
Description
Field na gagamitin sa pag-sort. Mga available na value:
- +created_at: Isaayos ayon sa oras ng paglikha nang paakyat (ascending).
- -created_at: Isaayos ayon sa oras ng paglikha nang pababa (descending).

Ibinabalik

Nagbabalik ng isang paginated na listahan ng 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

I-stream ang Multi-Color 3D Print Task

Ang endpoint na ito ay nag-stream ng real-time na mga update para sa isang multi-color 3D print task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Ang natatanging identifier ng multi-color 3D print task na i-stream.

Ibinabalik

Ibinabalik ang isang stream ng The 3D Print Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, ang response stream ay maglalaman lamang ng mga kinakailangang field na progress at status.

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
}

Ang 3D Print Task Object

Name
id
Type
string
Description
Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa mga task id bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng 3D Print task. Ang value ay print-multi-color.
Name
model_urls
Type
object
Description
Madadownload na URL patungo sa 3D model file na nabuo ni Meshy. Ang property para sa isang format ay hindi isasama kung hindi nabuo ang format sa halip na magbalik ng walang laman na string.
- Name
  3mf
  Type
  string
  Description
  Madadownload na URL patungo sa multi-color na 3MF file.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Ang value ng field na ito ay may kahulugan lamang kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp ng kung kailan nilikha ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp ng kung kailan nasimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
Timestamp ng kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay magiging 0.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task na ito. Nakikita kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ang credits ay ire-refund kapag nabigo).

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
}