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 rehiyong naiiwan ng isang hiwa ay palaging pinapatibay upang ang bawat bahagi ay ma-print nang solido.

Hindi napapanatili ng resulta ng split ang texture ng input. Tinatanggap ng Auto Split ang mga input na may texture, kaya hindi mo na kailangang buuin muli ang model gamit ang should_texture: false. Muli nitong binubuo ang mga hiniwang bahagi at nagtatalaga sa bawat isa ng isang flat na kulay ng vertex; walang input texture map na dinadala sa anumang i-export na format.

POST/openapi/v1/print/split

Create an Auto Split Task

Ang endpoint na ito ay lumilikha ng bagong Auto Split task. Pinuputol ng task na ito ang modelo ng isang naunang task sa magkakahiwalay na bahaging maaaring i-print, at ibinabalik ang segmented na modelo, kung saan 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 nito ay isasplit. 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 ginawa gamit ang Meshy 6 o Meshy 7 (ai_model meshy-6, meshy-7, meshy-7.1, o latest). Hindi suportado ang mga low-poly at Smart Topology (meshy-t2) na modelo. Tinatanggap ang isang textured na modelo, ngunit hindi dinadala ang texture nito sa resulta.

  • Name
    mode
    Type
    string
    default auto
    Description

    Kung paano hinahati ang modelo sa mga bahagi.

    Mga magagamit na value:

    • auto: Pinipili ng Meshy ang mga hiwa. Hindi pinapansin ang prompt.
    • by_parts: Humiwa ayon sa mga structural part na itinakda mo sa prompt, tulad ng ulo, braso, at katawan.
    • by_color: Humiwa ayon sa mga color region na itinakda mo sa prompt. Nangangailangan ng input na ginawa mula sa isang 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 nanggagaling sa source image, hindi 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

    Naglalarawan sa mga bahaging isasplit, sa anumang 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. Maaari ring 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 karakter. Dalawang paraan ng pagkabigo: ang isang paglalarawan na humihiling ng walang split sa lahat, o nagbibigay ng higit sa 10 bahagi, ay tinatanggihan ng 400 at walang sisingilin; ang isang paglalarawan na hindi maintindihan ng Meshy ay bumabalik sa auto, tumatakbo pa rin ang task at may bayad, at ang tugon nito ay may prompt_ignored: true.

  • Name
    target_formats
    Type
    array
    default ["glb"]
    Description

    Mga format na i-eeksport ang split na modelo. Ang mga format na sumusuporta sa mga scene object (glb, obj, fbx, usdz, blend, 3mf) ay nagdadala ng bawat bahagi bilang hiwalay na object; ang stl ay walang konsepto ng magkahiwalay na object, kaya pinagsasama nito ang bawat bahagi sa isang solid na inayos ayon sa layout (humiling ng 3mf para sa magkakahiwalay na napipiling bahagi sa isang slicer). Palaging nagagawa at ibinabalik sa model_urls ang glb; ilista ang anumang ibang format na gusto mong idagdag.

    Mga magagamit na value: glb, obj, fbx, stl, usdz, blend, 3mf.

  • Name
    layout
    Type
    string
    default assembled
    Description

    Kung paano inaayos ang mga bahagi sa bawat output format, at sa thumbnail.

    Mga magagamit na value:

    • assembled: Nananatili ang mga bahagi sa kinaroroonan nila sa source model.
    • on_plate: Inilalatag nang pantay at ikinakalat ang mga bahagi sa build plate, handa nang i-slice — ang parehong pag-aayos gaya ng On Plate view ng web app.

    Sa parehong layout, tinatanggal bago i-eksport ang isang collapsed na manipis na piraso o piraso na parang tuldok na natira mula sa isang hiwa, kaya bawat bahaging makukuha mo ay maaaring i-print. Ang mga format na sumusuporta sa mga scene object ay may isang object bawat bahagi; pinagsasama sila ng stl sa iisang solid.

  • Name
    connectors
    Type
    boolean
    default false
    Description

    Nagdaragdag ng mga mortise-and-tenon 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 magagamit na value: cube, cylinder.

  • Name
    connector_size
    Type
    number
    default 0.5
    Description

    Laki ng connector kaugnay sa cut surface.

    Wastong saklaw: 0.1 hanggang 0.8.

  • Name
    connector_height
    Type
    number
    default 0.1
    Description

    Kung gaano kalayo umaabot ang connector mula sa cut surface, kaugnay sa cut surface.

    Wastong saklaw: 0.1 hanggang 0.8.

Ibinabalik

Ang result property ng tugon ay naglalaman ng id ng bagong likhang Auto Split task.

Mga Paraan ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang request. Karaniwang mga dahilan:

    • Kulang na prompt: Kinakailangan ang prompt kapag ang mode ay by_parts o by_color.
    • Ang prompt ay walang inilalarawang split, o sobra sa dami ang bahagi: Tumatanggap ang by_parts / by_color ng 1 hanggang 10 pinangalanang piraso. Tatanggihan ang isang paglalarawan na humihiling na panatilihin ang modelo sa iisang piraso, o nagbibigay ng higit sa 10 bahagi. Walang sisingilin.
    • Hindi suportadong input task: Ang input_task_id ay dapat tumutukoy sa isang matagumpay na task ng suportadong uri, na ginawa gamit ang Meshy 6 o Meshy 7.
    • Walang reference image: Nangangailangan ang by_color ng input na ginawa mula sa isang na-upload na larawan.
    • Connector na labas sa saklaw: 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

    Nalampasan mo ang iyong rate limit. Ang mga request na by_parts at by_color ay nagbabahagi rin ng limitasyon sa pag-parse ng prompt na 12 request bawat minuto bawat account.

  • Name
    503 - Service Unavailable
    Description

    Pansamantalang hindi magagamit ang prompt-based splitting (by_parts at by_color). Subukan muli mamaya, 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.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 Auto Split Task

Kinukuha ng endpoint na ito ang isang Auto Split task gamit ang kaniyang ID.

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, kabilang ang lahat ng kaugnay na models at data. Hindi na maibabalik pa ang aksyong ito.

Path Parameters

  • Name
    id
    Type
    path
    Description

    Ang ID ng Auto Split task na ide-delete.

Status ng Task

Ang isang task na PENDING pa ay made-delete at ire-refund ang mga credits na ginamit noong oras ng paggawa nito.

Ang isang task na IN_PROGRESS na ay hindi maaaring i-delete: tatanggihan ang request nang may 409 Conflict at magpapatuloy pa rin tumakbo ang task. Hindi na maire-refund ang mga credits para sa isang task na sinimulan na ng worker, kaya kung ide-delete ito habang tumatakbo, mawawala sa iyo pareho ang credits at ang resulta. Hintayin muna itong umabot sa SUCCEEDED, FAILED, o CANCELED, saka ito i-delete.

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

Ibinabalik na Sagot

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

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

Ilista ang mga Auto Split Task

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

Mga Parameter

Mga opsyonal na attribute

  • Name
    page_num
    Type
    integer
    Description

    Numero ng pahina para sa pagination. Nagsisimula at defaults sa 1.

  • Name
    page_size
    Type
    integer
    Description

    Limitasyon ng laki ng pahina. Defaults sa 10 na item. Ang pinakamataas na pinapayagan ay 100 na item; ang mga mas malalaking value ay ikakulong sa 100.

  • Name
    sort_by
    Type
    string
    Description

    Field na gagamitin bilang batayan sa pag-sort. Mga available na value:

    • +created_at: Ayusin base sa oras ng paglikha nang pataas (ascending order).
    • -created_at: Ayusin base sa oras ng paglikha nang pababa (descending order).

Ibabalik

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

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

Stream an Auto Split Task

Ang endpoint na ito ay nag-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 buong task object gaya 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 bawat frame ay ang 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 lamang ang 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 texture_urls ay hindi kailanman napopulate para sa isang split at hindi ibinabalik. Ang mga property na napupunan habang tumatakbo ang task (thumbnail_url, model_urls, ang mga timestamp) ay laging naroroon, walang laman hangga't wala pang value, kaya hindi nagbabago ang set ng mga key sa pagitan ng PENDING at SUCCEEDED.

  • Name
    id
    Type
    string
    Description

    Kakaibang identifier para sa task. Bagaman gumagamit kami ng k-sortable UUID para sa task id bilang implementation detail, 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

    Mga URL na maidaunload sa split model, isa para sa bawat hiniling na format. Ang mga format na sumusuporta sa scene object ay pinananatili ang bawat bahagi bilang hiwalay na object; ang stl ay pinagsasanib ang mga ito sa isang solidong piraso. Ang property para sa isang format ay maaalis kung hindi ito hiniling.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL sa split model sa format na GLB.

    • Name
      obj
      Type
      string
      Description

      Downloadable URL sa split model sa format na OBJ.

    • Name
      fbx
      Type
      string
      Description

      Downloadable URL sa split model sa format na FBX.

    • Name
      stl
      Type
      string
      Description

      Downloadable URL sa split model sa format na STL. Ang lahat ng bahagi ay pinagsasanib sa isang solidong piraso; hilingin ang 3mf para sa mga bahaging maaaring hiwalay na piliin.

    • Name
      usdz
      Type
      string
      Description

      Downloadable URL sa split model sa format na USDZ.

    • Name
      blend
      Type
      string
      Description

      Downloadable URL sa split model sa format na Blender.

    • Name
      3mf
      Type
      string
      Description

      Downloadable URL sa split model sa format na 3MF.

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadable URL sa isang na-render na preview ng split model, may kanya-kanyang 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 binanggit na bahagi, kaya awtomatikong hinati ni Meshy ang model — ang mga pangalan ng bahagi sa resulta ay galing kay Meshy, hindi sa iyo. Naroroon mula sa PENDING pa lang. Hindi kasama para sa mga auto task at kapag sinunod ang prompt.

  • Name
    part_count
    Type
    integer
    Description

    Bilang ng mga maipirinta na bahaging nabuo ng split. Ang mga format na sumusuporta sa scene object ay may isang object kada bahagi; ang stl ay pinagsasanib ang mga ito sa isang solidong piraso, at ang bilang ay nag-uulat pa rin ng mga bahagi. Ang mga nabuwal na maliliit na piraso na hindi natapos gawin ng segmentation na isang maipirintang piraso ay aalisin sa mga file bago i-export at hindi kinabibilangan sa bilang.

  • 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 nakaraang 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 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

    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 credit na ginamit ng task na ito. Laging naroroon: 10 kapag natanggap na ang task, at 0 para sa mga FAILED task dahil ang bayad ay ibinabalik kapag nabigo. Ang pagtanggal ng isang task habang ito ay PENDING ay nagpapabalik 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
}