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 gumagawa ng bagong multi-color 3D print task. Iko-convert ng task na ito ang isang 3D model sa isang multi-color 3MF file na angkop para sa 3D printing.

Mga Parameter

Isa lamang sa input_task_id o model_url ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang magkakaroon ng priority.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang matagumpay na task na gagamitin bilang input. 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
Maximum na bilang ng kulay sa output palette.
Valid na saklaw: 1 hanggang 16.
Name
style
Type
string
default realistic
Description
Visual na color style ng ginawang 3MF file.
Mga available na value:
- realistic: Kinukuha ang mga kulay direkta mula sa texture ng model para sa magandang detalye, katulad ng litrato. Nagreresulta sa mas malaking file.
- cartoon: Pinapatag ang mga kulay sa malinis at pantay na mga rehiyon para sa isang stylized na hitsura. Nagreresulta sa mas maliit na file.
Ang input ay dapat may dalang kulay: 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 na mga kulay. Tatanggihan ang mga modelong walang texture (puti) — tingnan ang model_missing_texture.

Mga Ibinabalik

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

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang mga dahilan:
- Nawawalang parameter: Kailangang ibigay ang alinman sa model_url o input_task_id.
- Di-wastong format ng model: Ang model_url ay tumutukoy sa isang file na may hindi suportadong extension (.glb at .fbx lamang ang sinusuportahan).
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Di-wastong input task: Dapat tumukoy ang input_task_id sa isang matagumpay na task.
- Di-wastong max_colors: Dapat ang value ay nasa pagitan ng 1 at 16.
- Di-wastong style: Dapat ang value ay realistic o cartoon.
- Walang pinagmulan ng kulay: Ang input model ay walang base color texture (ang realistic ay nangangailangan 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 modelong may vertex color. Ang mga .fbx na upload ay sinusuri matapos i-normalize ng task ang mga ito at nabibigo na may 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 maisagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang iyong rate limit.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
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
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

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

Kunin ang 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

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
}