Multi-Color Print API

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

POST/openapi/v1/print/multi-color

Gumawa ng Multi-Color 3D Print Task

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

Tumatakbo ang task na ito sa background. Para sa karaniwang tagal nito, tingnan ang Processing Times.

Mga Parameter

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

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

Name
model_url
Type
string
Kinakailangan
Description
Publicly accessible na URL ng isang .glb o .fbx model, o isang base64 data: URL ng GLB (data:model/gltf-binary;base64,...). Ang .fbx ay dapat ipadala bilang http o https URL.
Pinakamataas na laki ng file: 400 MB para sa http o https URL, 100 MB para sa data: URI.
Ang file na higit sa 100 MB ay maaaring magkaroon ng hanggang 8,000,000 faces. Ang mga faces ay binibilang bilang triangles: ang isang quad ay binibilang bilang 2, at ang mesh na iginuhit nang higit sa isang beses ay binibilang isang beses bawat kopya. Para sa higit sa 100 MB, ang isang FBX file ay dapat binary FBX 7.1 o mas bago, at ang isang GLB file ay hindi dapat gumagamit ng Draco compression.

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 istilo ng kulay ng nabuong 3MF file.
Mga available na value:
- realistic: Dumadampot ng mga kulay direkta mula sa texture ng model para sa pino, photo-realistic na detalye. Gumagawa ng mas malaking file.
- cartoon: Pinapapantay ang mga kulay sa malinis, pare-parehong rehiyon para sa may-istilong hitsura. Gumagawa ng mas maliit na file.
Dapat may dalang kulay ang input: ang realistic ay nangangailangan ng iisang base color texture na may UV coordinates sa bawat bahagi ng mesh; ang cartoon ay tumatanggap din ng per-vertex colors. Tinatanggihan ang mga walang texture (puting) model — tingnan ang model_missing_texture.
Name
max_depth
Type
integer
default 4
Description
Subdivision depth na ginagamit sa pagsample ng mga kulay ng texture papunta sa mesh. Mas mataas na value ay nakakakuha ng mas pinong detalye ng kulay ngunit may mas malaking file bilang kapalit. Naaangkop lamang sa realistic na istilo; hindi pinapansin para sa cartoon.
Valid na saklaw: 3 hanggang 6.
Name
printer_brand
Type
string
default bambu
Description
Brand ng printer kung saang slicer preset isinusulat sa 3MF, para mabuksan ang file sa slicer ng brand na iyon na may katugmang printer, filament, at process profile. Bawat brand ay gumagamit ng kanilang default na printer na may 0.4 mm nozzle.
Mga available na value: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Mga Ibinabalik

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

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang dahilan:
- Kulang na parameter: Dapat ibigay alinman sa model_url o input_task_id.
- Hindi valid na format ng model: Ang model_url ay tumutukoy sa file na may hindi suportadong extension (.glb at .fbx lamang ang suportado).
- Hindi naaabot na URL: Hindi ma-download ang model_url.
- Masyadong malaki ang model file: Lumalampas sa 400 MB (http o https URL) o 100 MB (data: URI) ang file ng model_url.
- Masyadong maraming faces: Ang file ng model_url ay higit sa 100 MB at may higit sa 8,000,000 faces. Bawasan ang bilang ng faces, pagkatapos ay ipadala ulit ang file.
- ASCII FBX na higit sa 100 MB: Ang file ng model_url ay isang ASCII FBX na higit sa 100 MB. Ipadala ito bilang binary FBX o GLB.
- Hindi mabasang model file: Ang file ng model_url ay higit sa 100 MB at hindi mabasa ang header nito, halimbawa isang Draco-compressed GLB, o isang binary FBX na mas luma sa 7.1.
- Masyadong kumplikado ang header ng model: Ang file ng model_url ay higit sa 100 MB at ang header nito ay may masyadong maraming mesh, node, o record na dapat suriin. Bawasan ang bilang ng mga object sa file, pagkatapos ay ipadala ulit ito.
- Hindi valid na input task: Ang input_task_id ay dapat tumutukoy sa isang matagumpay na task.
- Hindi valid na max_colors: Dapat nasa pagitan ng 1 at 16 ang value.
- Hindi valid na style: Dapat realistic o cartoon ang value.
- Hindi valid na max_depth: Dapat nasa pagitan ng 3 at 6 ang value.
- Hindi valid na printer_brand: Dapat isa sa mga brand na nakalista sa itaas ang value.
- Walang pinagmumulan ng kulay: Ang input model ay walang base color texture (realistic ay nangangailangan ng iisa, may UVs, sa bawat bahagi ng mesh) at walang vertex colors (cartoon ay tumatanggap ng alinman). I-texture muna ang model, o gamitin ang cartoon para sa mga vertex-colored na model. Ang mga .fbx na upload ay sinusuri matapos i-normalize ng task ang mga ito at nabibigo sa model_missing_texture sa halip.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits para gawin 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

Kunin ang isang Multi-Color 3D Print Task

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

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

Mag-delete ng Multi-Color 3D Print Task

Permanenteng binubura ng endpoint na ito ang isang multi-color 3D print task, kasama ang lahat ng kaugnay na modelo at data. Hindi na maibabalik ang aksyong ito.

Mga Path Parameter

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

Status ng Task

Ang task na PENDING pa ay binubura at ire-refund ang mga credits na nagamit noong oras ng paglikha nito.

Ang task na IN_PROGRESS na ay hindi maaaring i-delete: tatanggihan ang request na may 409 Conflict at magpapatuloy ang pagtakbo ng task. Ang mga credits para sa task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya kung ide-delete ito habang tumatakbo, mawawala sa iyo kapwa ang credits at ang resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

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

Ibinabalik

Nagbabalik ng 200 OK kung 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

I-list 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 mga attribute

Name
page_num
Type
integer
Description
Numero ng pahina para sa pagination. Nagsisimula at nagde-default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa sukat ng pahina. Nagde-default sa 10 items. Ang pinakamataas na pinapayagan ay 100 items.
Name
sort_by
Type
string
Description
Field na gagamitin para mag-sort. Mga magagamit na halaga:
- +created_at: Pagsunod-sunurin ayon sa oras ng paggawa nang pataas (ascending order).
- -created_at: Pagsunod-sunurin ayon sa oras ng paggawa nang pababa (descending order).

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 na 3D Print Task

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

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa multi-color na 3D print task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The 3D Print Task Objects bilang Server-Sent Events.

Para sa mga task na nasa PENDING o IN_PROGRESS, isasama lamang ng response stream ang 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
Downloadable URL sa 3D model file na nabuo ng Meshy. Ang property para sa isang format ay aalisin kung hindi na-generate ang format sa halip na magbalik ng isang walang-laman na string.
- Name
  3mf
  Type
  string
  Description
  Downloadable URL sa multi-color 3MF file.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nagsisimula 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.
Makabuluhan lamang ang value ng field na ito kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nalikha ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan nagsimula ang task, sa milliseconds. Kung hindi pa nagsisimula ang task, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
Timestamp 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 mga credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ang mga 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
}