Auto Split API

Hatiin ang isang 3D model sa magkahiwalay na mga bahaging maaaring i-print — awtomatiko, ayon sa mga bahaging pinangalanan mo, o ayon sa color region — na may opsyonal na mga connector; ang mga manipis na bahagi na naiwan ng isang hiwa ay palaging pinapatibay para ang bawat bahagi ay mag-print nang solido.

Kasalukuyang sinusuportahan ng Auto Split ang mga model na walang texture lamang. Para sa Image to 3D at Multi-Image to 3D, buuin ang input gamit ang should_texture na itinakda sa false. Ang input na may texture ay tatanggihan na may 400.

POST/openapi/v1/print/split

Gumawa ng Auto Split Task

Ang endpoint na ito ay gumagawa ng bagong Auto Split task. Pinuputol ng task na ito ang modelo ng isang naunang task tungo sa hiwa-hiwalay na maipi-print na bahagi at ibinabalik ang segmented na modelo, kung saan ang bawat bahagi ay sarili nitong object sa file.

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang matagumpay na task na ang modelo ay ii-split. 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 ang modelo nito ay dapat nabuo gamit ang Meshy 6 o Meshy 7 (ai_model meshy-6, meshy-7, o latest). Hindi suportado ang low-poly at Smart Topology (meshy-t2) na mga modelo.

Name
mode
Type
string
default auto
Description
Kung paano hinahati ang modelo sa mga bahagi.
Mga available na value:
- auto: Si Meshy ang pipili ng 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 rehiyon ng kulay na pinangalanan mo sa prompt. Nangangailangan ng input na nabuo mula sa isang na-upload na larawan (Image to 3D o Multi-Image to 3D); ang ibang input ay tinatanggihan na may 400.

Naaangkop lamang kapag mode = by_parts or by_color

Name
prompt
Type
string
Kinakailangan
Description
Naglalarawan sa mga bahaging hahatiin, sa kahit anong wika. Nagbabasa si Meshy ng 1 hanggang 10 pangalan ng bahagi mula rito, kaya ipangalan 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. Hanggang 600 na character. May dalawang failure mode: ang isang paglalarawan na nagbabasa bilang isang split ngunit nagpapangalan ng mas mababa sa dalawang bahagi (halimbawa split into individual parts) ay tinatanggihan na may 400 at walang sisingilin; ang isang paglalarawan na talagang hindi mababasa ni Meshy ay babalik sa auto, tatakbo pa rin ang task at sisingilin, at ang response nito ay magdadala ng prompt_ignored: true.

Name
target_formats
Type
array
default ["glb"]
Description
Mga format na i-eexport ang split na modelo. Ang bawat bahagi ay hiwalay na object sa bawat format. Palaging ginagawa at ibinabalik ang glb sa model_urls; ilista ang anumang ibang format na gusto mo bilang karagdagan.
Mga available na value: glb, obj, fbx, usdz, blend, 3mf.
Name
layout
Type
string
default assembled
Description
Kung paano inaayos ang mga bahagi sa bawat output format, at sa thumbnail.
Mga available na value:
- assembled: Ang mga bahagi ay nananatili kung saan sila inilagay ng source model.
- on_plate: Ang mga bahagi ay pinapatag at ikinakalat sa build plate, handa nang i-slice — ang parehong arrangement ng On Plate view ng web app.
Sa parehong layout, ang mga na-export na file ay may isang object bawat bahagi at wala nang iba pa: ang isang collapsed sliver o point-like na piraso na natira mula sa isang hiwa ay tinatanggal bago mag-export, kaya ang bawat object na makikita mo sa file ay maipi-print.
Name
connectors
Type
boolean
default false
Description
Nagdadagdag 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 cut surface.
Mga available na value: cube, cylinder.
Name
connector_size
Type
number
default 0.5
Description
Laki ng connector kaugnay ng cut surface.
Valid na saklaw: 0.1 hanggang 0.8.
Name
connector_height
Type
number
default 0.1
Description
Gaano kalayo umaabot ang connector mula sa cut surface, kaugnay ng cut surface.
Valid na saklaw: 0.1 hanggang 0.8.

Ibinabalik

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

Mga Failure Mode

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang dahilan:
- Kulang na prompt: Kinakailangan ang prompt kapag ang mode ay by_parts o by_color.
- Ang prompt ay nagpapangalan ng mas mababa sa dalawang bahagi: Ang by_parts / by_color ay nangangailangan ng kahit dalawang pinangalanang piraso (halimbawa head, torso, base); ang isang generic na instruksyon tulad ng split into individual parts ay tinatanggihan. Walang sisingilin.
- Hindi suportadong input task: Ang input_task_id ay dapat tumutukoy sa isang matagumpay na task ng isang suportadong uri, na nabuo gamit ang Meshy 6 o Meshy 7.
- May texture na input: May mga texture ang input model. Sa ngayon, mga modelong walang texture lamang ang suportado.
- Walang reference image: Ang by_color ay nangangailangan ng input na nabuo mula sa isang na-upload na larawan.
- Hindi suportadong format: Naglalaman ang target_formats ng stl.
- Out-of-range na connector: Ang connector_size o connector_height ay wala sa saklaw na 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 upang 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
Nalagpasan mo na ang iyong rate limit. Ang mga request na by_parts at by_color ay nagbabahagi rin ng prompt-parsing limit na 12 request bawat minuto bawat account.
Name
503 - Service Unavailable
Description
Pansamantalang hindi available ang prompt-based na paghahati (by_parts at by_color). Subukan muli sa ibang pagkakataon, o gamitin ang mode: "auto", na hindi apektado. Walang sisingilin.

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.cn/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.cn/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 Auto Split Task

Kinukuha ng endpoint na ito ang isang 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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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

Burahin ang isang Auto Split Task

Permanenteng binubura ng endpoint na ito ang isang Auto Split task, kasama ang lahat ng kaugnay na modelo at datos. Hindi na maibabalik ang aksyong ito.

Mga Path Parameter

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

Mga Ibinabalik na Halaga

Nagbabalik ng 200 OK kapag matagumpay.

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/split

Ilista ang mga Auto Split Task

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kunin ang isang listahan ng mga Auto Split task.

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 laki ng pahina. Ang default ay 10 na item. Ang pinakamataas na pinapayagan ay 100 na item; ang mas malalaking value ay pinipigilan 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 paglikha nang pataas.
- -created_at: Isaayos ayon sa oras ng paglikha nang pababa.

Mga Ibinabalik

Nagbabalik ng isang paginated na listahan ng Mga Auto Split Task Object.

Request

GET

/openapi/v1/print/split

curl https://api.meshy.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/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

Stream an Auto Split Task

Ang endpoint na ito ay nagsa-stream 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.

Bawat message event ay nagdadala ng kumpletong task object gaya ng ibinabalik ng Retrieve an Auto Split Task, kabilang 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, part_count at parts 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.cn/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.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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 nagdadala lamang ng mga property sa ibaba. Ang mga generation-prompt field na kasama sa ibang task object (name, object_prompt, texture_prompt at iba pa), ang iisang model_url, at ang texture_urls ay hindi kailanman napupunuan para sa isang split at hindi ibinabalik. Ang mga property na napupunuan habang tumatakbo ang task (thumbnail_url, model_urls, ang mga timestamp) ay palaging naroroon, walang laman hanggang magkaroon ng halaga ang mga ito, 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 pagpapalagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng task. Ang halaga ay print-split.
Name
model_urls
Type
object
Description
Mga URL na maaaring i-download para sa split model, isa para sa bawat hiniling na format. Ang bawat bahagi ay isang hiwalay na object sa file. Ang property para sa isang format ay hindi isasama kung hindi hiniling ang format na iyon.
- Name
  glb
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format na GLB.
- Name
  obj
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format na OBJ.
- Name
  fbx
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format na FBX.
- Name
  usdz
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format na USDZ.
- Name
  blend
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format ng Blender.
- Name
  3mf
  Type
  string
  Description
  URL na maaaring i-download para sa split model sa format na 3MF.
Name
thumbnail_url
Type
string
Description
URL na maaaring i-download para sa isang na-render na preview ng split model, na may natatanging kulay ang bawat bahagi, sa hiniling na layout.
Name
prompt_ignored
Type
boolean
Description
true kapag ang prompt ng isang by_parts o by_color request ay walang pinangalanang bahagi, kaya awtomatikong hinati ni Meshy ang model sa halip — ang mga pangalan ng bahagi sa resulta ay galing kay Meshy, hindi sa iyo. Naroroon mula pa sa PENDING. Hindi isinasama para sa mga auto task at sa tuwing sinunod ang prompt.
Name
part_count
Type
integer
Description
Bilang ng mga naipi-print na bahagi sa split model — isa para sa bawat object sa mga na-export na file. Ang mga na-collapse na manipis na piraso na hindi naging naipi-print na piraso ng segmentation ay inaalis sa mga file bago i-export at hindi binibilang.
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 halaga ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Makabuluhan lamang ang halaga ng field na ito kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nilikha 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 tapos 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 nagamit ng task na ito. Palaging naroroon: 10 kapag natanggap na ang task, at 0 para sa mga FAILED na task dahil ang singil ay ibinabalik kapag nabigo. Ang pagbura sa isang task habang ito ay PENDING pa ay nagbabalik din nito.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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
}