Auto Split API

Hatiin ang isang 3D model sa magkakahiwalay na bahaging maaaring i-print — awtomatiko, ayon sa mga bahaging pinangalanan mo, o ayon sa rehiyon ng kulay — na may opsyonal na mga connector; ang mga manipis na bahagi na naiiwan ng isang hiwa ay palaging pinapalakas upang ang bawat bahagi ay mag-print nang solido.

Hindi pinapanatili ng resulta ng split ang input texture. Tumatanggap ang Auto Split ng mga textured na input, kaya hindi mo na kailangang i-regenerate ang model gamit ang should_texture: false. Muli nitong binubuo ang mga nahiwang bahagi at binibigyan ang bawat isa ng flat vertex color; walang input texture map na dinadala sa alinmang na-export na format.

POST/openapi/v1/print/split

Create an Auto Split Task

Ang endpoint na ito ay gumagawa ng bagong Auto Split task. Pinuputol ng task na ito ang modelo ng naunang task sa mga bahaging maaaring i-print nang hiwalay, at ibinabalik ang nahating modelo, kung saan bawat bahagi ay sarili nitong object sa file.

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

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng matagumpay na task kung saan kukunin ang modelong hahatiin. Mga suportadong uri ng task: Image to 3D, Multi-Image to 3D, Text to 3D (preview), Remesh, Convert, at Resize. Dapat ang status ng task ay SUCCEEDED, at dapat na ang modelo nito ay nabuo gamit ang Meshy 6 o Meshy 7 (ai_model meshy-6, meshy-7, meshy-7.1, o latest). Hindi suportado ang low-poly at Smart Topology (meshy-t2, meshy-t2.5) na mga modelo. Tinatanggap ang modelong may texture, ngunit hindi dadalhin ang texture nito sa resulta.

Name
mode
Type
string
default auto
Description
Paano hahatiin ang modelo sa mga bahagi.
Mga magagamit na value:
- auto: Pipiliin ng Meshy ang mga hiwa. Hindi pinapansin ang prompt.
- by_parts: Hiwain ayon sa mga structural na bahaging pinangalanan mo sa prompt, tulad ng ulo, braso, at katawan.
- by_color: Hiwain ayon sa mga color region na pinangalanan mo sa prompt. Kailangan ng input na nabuo mula sa na-upload na larawan (Image to 3D o Multi-Image to 3D); tatanggihan ang ibang input na may 400. Ang mga hangganan ng color region ay galing sa source image, hindi mula sa texture ng input model. Para sa Multi-Image to 3D, ginagamit ng Auto Split ang unang source image.

Naaangkop lamang kapag mode = by_parts or by_color

Name
prompt
Type
string
Kinakailangan
Description
Inilalarawan ang mga bahaging hahatiin, sa kahit anong wika. Nagbabasa ang Meshy ng 1 hanggang 10 pangalan ng bahagi mula rito, kaya pangalanan ang mga piraso sa halip na ilarawan ang modelo, halimbawa split into the figure and the base, o head, torso, left arm, right arm, legs. Okay lang na pangalanan ang isang bahagi lamang: ang lahat ng hindi mo pinangalanan ay magiging isang natitirang bahagi, kaya ang the head ay naghahati sa modelo sa ulo at sa iba pa, tulad ng sa web app. Hanggang 600 na character. Ang paglalarawan na humihiling na huwag hatiin ang modelo, o nagpangalan ng higit sa 10 bahagi, ay tatanggihan na may 400 at walang sisingilin. Kung hindi makabasa ang Meshy ng anumang pangalan ng bahagi mula sa paglalarawan, hahatiin nito ayon sa mga bahaging nakikilala nito sa reference image ng modelo sa halip, sa mode na pinili mo: tatakbo at sisingilin pa rin ang task, at magkakaroon ito ng prompt_ignored: true. Kung walang reference image ang modelo, o kung mas kaunti sa dalawang bahagi ang nahanap ng Meshy dito, tatanggihan ang kahilingang iyon na may 400 sa halip at walang sisingilin.

Name
target_formats
Type
array
default ["glb"]
Description
Mga format kung saan ii-export ang nahating modelo. Ang mga format na sumusuporta sa scene object (glb, obj, fbx, usdz, blend, 3mf) ay may bawat bahagi bilang hiwalay na object; wala namang konsepto ng hiwalay na object ang stl, kaya pinagsasama nito ang bawat bahagi sa isang solidong bagay na nakaayos ayon sa layout (hilingin ang 3mf para sa mga bahaging maaaring piliin nang hiwalay sa slicer). Lagi ginagawa at ibinabalik ang glb sa model_urls; ilista ang alinmang ibang format na gusto mo bilang karagdagan.
Mga magagamit na value: glb, obj, fbx, stl, usdz, blend, 3mf.
Name
layout
Type
string
default assembled
Description
Paano nakaayos ang mga bahagi sa bawat output format, at sa thumbnail.
Mga magagamit na value:
- assembled: Nananatili ang mga bahagi sa posisyong kinaroroonan nila sa source model.
- on_plate: Inilalatag at ikinakalat ang mga bahagi sa build plate, handa nang i-slice — ang parehong ayos ng On Plate view ng web app.
Sa parehong layout, inaalis bago mag-export ang anumang nabuwal na manipis na piraso o parang punto na natira mula sa isang hiwa, kaya ang bawat bahaging makukuha mo ay maaaring i-print. Ang mga format na sumusuporta sa scene object ay may isang object kada bahagi; pinagsasama ng stl ang mga ito sa iisang solidong bagay.
Name
connectors
Type
boolean
default false
Description
Nagdaragdag ng mortise-and-tenon na mga connector sa bawat hiwa upang magkasya ang mga naka-print na bahagi.

Naaangkop lamang kapag connectors = true

Name
connector_type
Type
string
default cube
Description
Ang hugis ng connector sa bawat ibabaw ng hiwa.
Mga magagamit na value: cube, cylinder.
Name
connector_size
Type
number
default 0.5
Description
Sukat ng connector kaugnay sa ibabaw ng hiwa.
Valid na saklaw: 0.1 hanggang 0.8.
Name
connector_height
Type
number
default 0.1
Description
Hanggang saang layo umaabot ang connector mula sa ibabaw ng hiwa, kaugnay sa ibabaw ng hiwa.
Valid na saklaw: 0.1 hanggang 0.8.

Mga Ibabalik

Ang result property ng response ay naglalaman ng id ng bagong gawang Auto Split task.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang kahilingan. Mga karaniwang sanhi:
- Walang prompt: Kailangan ang prompt kapag ang mode ay by_parts o by_color.
- Walang inilalarawang hiwa sa prompt, o sobrang dami ng bahagi: Tumatanggap ang by_parts / by_color ng 1 hanggang 10 pinangalanang piraso. Ang paglalarawang humihiling na panatilihin ang modelo sa iisang piraso, o nagpangalan ng higit sa 10 bahagi, ay tatanggihan. Walang sisingilin.
- Hindi suportadong input task: Dapat tumuturo ang input_task_id sa isang matagumpay na task ng suportadong uri, na nabuo gamit ang Meshy 6 o Meshy 7.
- Walang reference image: Kailangan ng by_color ang input na nabuo mula sa na-upload na larawan.
- Connector na labas sa saklaw: Ang connector_size o connector_height ay labas sa 0.1 hanggang 0.8.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits para isagawa ang task na ito.
Name
404 - Not Found
Description
Ang input_task_id ay hindi umiiral o hindi kabilang sa iyong account.
Name
429 - Too Many Requests
Description
Nalampasan mo na ang iyong rate limit. Ang mga request na by_parts at by_color ay may karagdagang shared na limit sa pag-parse ng prompt na 12 request kada minuto bawat account.
Name
503 - Service Unavailable
Description
Pansamantalang hindi magagamit ang pag-split na batay sa prompt (by_parts at by_color). Subukang muli mamaya, o gamitin ang mode: "auto", na hindi naapektuhan. Walang sisingilin.

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

GET/openapi/v1/print/split/:id

Kunin ang Isang Auto Split Task

Ang endpoint na ito ay kumukuha ng Auto Split task gamit ang ID nito.

Mga Parameter

Name
id
Type
path
Description
Ang ID ng Auto Split task na kukunin.

Ibinabalik

Ang Auto Split Task object.

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

DELETE/openapi/v1/print/split/:id

Mag-delete ng Auto Split Task

Ang endpoint na ito ay permanenteng nagde-delete ng isang Auto Split task, kasama ang lahat ng kaugnay na modelo at datos. Hindi na mababawi ang aksyong ito.

Mga Path Parameter

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

Katayuan ng Task

Ang isang task na PENDING pa ay dine-delete at ang mga credit na nagamit noong oras ng paglikha nito ay ire-refund.

Ang isang 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 credit para sa isang task na nasimulan na ng worker ay hindi na maire-refund, kaya ang pag-delete nito habang tumatakbo ay magiging sanhi ng pagkawala ng credits at ng resulta. Hintayin munang umabot ito sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay dine-delete nang walang refund.

Mga Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay IN_PROGRESS.

Request

DELETE

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/split/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/split

List Auto Split Tasks

Pinapayagan ka ng endpoint na ito na kumuha ng listahan ng mga Auto Split task.

Mga Parameter

Opsyonal na attributes

Name
page_num
Type
integer
Description
Numero ng page para sa pagination. Nagsisimula at nag-default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa laki ng page. Nag-default sa 10 item. Ang maximum na pinapayagan ay 100 item; ang mas malalaking value ay iklinamp (clamped) sa 100.
Name
sort_by
Type
string
Description
Field na gagamitin sa pag-sort. Mga available na value:
- +created_at: Isaayos ayon sa oras ng paggawa nang pataas (ascending).
- -created_at: Isaayos ayon sa oras ng paggawa nang pababa (descending).

Ibinabalik

Nagbabalik ng isang pinaged (paginated) na listahan ng The Auto Split Task Objects.

Request

GET

/openapi/v1/print/split

curl https://api.meshy.ai/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/split/:id/stream

I-stream ang Auto Split Task

Ang endpoint na ito ay nagbibigay ng real-time na mga update para sa isang Auto Split task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Auto Split task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The Auto Split Task Objects bilang Server-Sent Events.

Ang bawat message event ay nagdadala ng buong task object tulad ng ibinabalik ng Retrieve an Auto Split Task, kasama ang consumed_credits, ang mga timestamp, at prompt_ignored; habang ang task ay PENDING o IN_PROGRESS, ang mga field na nagbabago sa pagitan ng mga frame ay progress, status, started_at at preceding_tasks, at lumalabas ang model_urls, thumbnail_url at part_count kapag naabot na nito ang SUCCEEDED. Ang isang error event ay nagdadala lamang ng status_code at message, kaya mag-branch batay sa pangalan ng event bago basahin ang status.

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is 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-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Ang Auto Split Task Object

Ang isang Auto Split task ay may mga property lamang sa ibaba. Ang mga generation-prompt field na kasama sa ibang task object (name, object_prompt, texture_prompt at iba pa), ang nag-iisang model_url, at ang texture_urls ay hindi kailanman napupunan para sa isang split at hindi ito ibinabalik. Ang mga property na napupunan habang tumatakbo ang task (thumbnail_url, model_urls, ang mga timestamp) ay laging naroroon, walang laman hanggang mabigyan sila ng value, kaya hindi nagbabago ang set ng mga key sa pagitan ng PENDING at SUCCEEDED.

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 task. Ang value ay print-split.
Name
model_urls
Type
object
Description
Madodownload na URL patungo sa na-split na modelo, isa bawat hiniling na format. Ang mga format na sumusuporta sa scene object ay pinapanatili ang bawat parte bilang hiwalay na object; pinagsasama ng stl ang mga ito sa iisang solid. Ang property para sa isang format ay aalisin kung ang format ay hindi hiniling.
- Name
  glb
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa GLB na format.
- Name
  obj
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa OBJ na format.
- Name
  fbx
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa FBX na format.
- Name
  stl
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa STL na format. Lahat ng parte ay pinagsasama sa iisang solid; hilingin ang 3mf para sa mga parteng bukod-bukod na mapipili.
- Name
  usdz
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa USDZ na format.
- Name
  blend
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa Blender na format.
- Name
  3mf
  Type
  string
  Description
  Madodownload na URL patungo sa na-split na modelo sa 3MF na format.
Name
thumbnail_url
Type
string
Description
Madodownload na URL patungo sa isang na-render na preview ng na-split na modelo, kung saan bawat parte ay may kakaibang kulay, sa hiniling na layout.
Name
prompt_ignored
Type
boolean
Description
true kapag ang prompt ng isang by_parts o by_color na request ay walang pinangalanang bahagi, kaya ang Meshy ay awtomatikong hinati ang modelo sa halip — ang mga pangalan ng parte sa resulta ay sa Meshy, hindi sa iyo. Naroroon mula pa sa PENDING. Hindi kasama para sa mga auto na task at tuwing sinunod ang prompt.
Name
part_count
Type
integer
Description
Bilang ng mga printable na parteng nagawa ng split. Ang mga format na sumusuporta sa scene object ay may isang object bawat parte; pinagsasama ng stl ang mga ito sa iisang solid, at patuloy na iniuulat ng count ang mga parte. Ang mga nabuwag na sliver na hindi naisali ng segmentation bilang isang printable na piraso ay inaalis sa mga file bago i-export at hindi binibilang.
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, CANCELED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Ang value ng field na ito ay makabuluhan lamang kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nagawa ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp 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 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. Kung tinanggihan ng safety check ng model provider ang input model, mabibigo ang task na may task_error.type na invalid_input at code na provider_content_refused. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng mga credit na nagamit ng task na ito. Laging naroroon: 10 kapag natanggap na ang task, at 0 para sa mga FAILED na task dahil ang singil ay na-refund kapag nabigo. Ang pagtanggal ng task habang ito ay PENDING pa rin ay nagre-refund din nito.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}