API Auto Split

Pecahkan model 3D kepada bahagian-bahagian yang boleh dicetak secara berasingan — secara automatik, mengikut bahagian yang anda namakan, atau mengikut kawasan warna — dengan penyambung pilihan; kawasan nipis yang ditinggalkan oleh satu potongan sentiasa diperkukuh supaya setiap bahagian dicetak secara pejal.

Hasil pemisahan tidak mengekalkan tekstur input. Auto Split menerima input bertekstur, jadi anda tidak perlu menjana semula model dengan should_texture: false. Ia membina semula bahagian yang dipotong dan memberikan setiap satu warna verteks rata; tiada peta tekstur input dibawa ke dalam mana-mana format eksport.

POST/openapi/v1/print/split

Create an Auto Split Task

Endpoint ini mencipta tugas Auto Split yang baharu. Tugas ini memotong model daripada tugas sebelumnya kepada bahagian yang boleh dicetak secara berasingan dan mengembalikan model yang disegmenkan, dengan setiap bahagian sebagai objek tersendiri dalam fail.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Processing Times.

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas yang berjaya yang modelnya hendak dipisahkan. Jenis tugas yang disokong: Image to 3D, Multi-Image to 3D, Text to 3D (pratonton), Remesh, Convert, dan Resize. Tugas itu mesti mempunyai status SUCCEEDED, dan modelnya mesti dijana menggunakan Meshy 6 atau Meshy 7 (ai_model meshy-6, meshy-7, meshy-7.1, atau latest). Model low-poly dan Smart Topology (meshy-t2, meshy-t2.5) tidak disokong. Model bertekstur diterima, dan tekstur model itu tidak dibawa ke dalam hasil.

Name
mode
Type
string
lalai auto
Description
Cara model dibahagikan kepada beberapa bahagian.
Nilai yang tersedia:
- auto: Meshy memilih titik potongan. prompt diabaikan.
- by_parts: Potong mengikut bahagian struktur yang anda namakan dalam prompt, seperti kepala, lengan, dan torso.
- by_color: Potong mengikut kawasan warna yang anda namakan dalam prompt. Memerlukan input yang dijana daripada imej yang dimuat naik (Image to 3D atau Multi-Image to 3D); input lain ditolak dengan 400. Sempadan kawasan warna diambil daripada imej sumber, bukan daripada tekstur model input. Untuk Berbilang Imej ke 3D, Auto Split menggunakan imej sumber pertama.

Hanya berlaku apabila mode = by_parts or by_color

Name
prompt
Type
string
Diperlukan
Description
Menerangkan bahagian untuk dipisahkan, dalam mana-mana bahasa. Meshy membaca 1 hingga 10 nama bahagian daripadanya, jadi namakan bahagian-bahagian itu dan bukannya menerangkan model, contohnya split into the figure and the base, atau head, torso, left arm, right arm, legs. Menamakan satu bahagian sahaja juga boleh: segala yang tidak anda namakan akan menjadi satu bahagian yang berbaki, jadi the head memisahkan model kepada kepala dan selebihnya, sama seperti dalam aplikasi web. Sehingga 600 aksara. Penerangan yang meminta supaya langsung tidak dipisahkan, atau menamakan lebih daripada 10 bahagian, akan ditolak dengan 400 dan tiada caj dikenakan. Jika Meshy tidak dapat membaca sebarang nama bahagian daripada penerangan tersebut, ia akan memisahkan mengikut bahagian yang dikenal pasti dalam imej rujukan model itu, dalam mode yang anda pilih: tugas tetap dijalankan dan dicaj, dan ia membawa prompt_ignored: true. Jika model tidak mempunyai imej rujukan, atau Meshy mendapati kurang daripada dua bahagian di dalamnya, permintaan itu akan ditolak dengan 400 sebaliknya dan tiada caj dikenakan.

Name
target_formats
Type
array
lalai ["glb"]
Description
Format untuk mengeksport model yang dipisahkan. Format yang menyokong objek adegan (glb, obj, fbx, usdz, blend, 3mf) membawa setiap bahagian sebagai objek berasingan; stl tidak mempunyai konsep objek berasingan, jadi ia menggabungkan setiap bahagian menjadi satu pepejal yang disusun mengikut layout (mintalah 3mf untuk bahagian yang boleh dipilih secara berasingan dalam slicer). glb sentiasa dihasilkan dan dikembalikan dalam model_urls; senaraikan mana-mana format lain yang anda mahu sebagai tambahan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, blend, 3mf.
Name
layout
Type
string
lalai assembled
Description
Cara bahagian-bahagian disusun dalam setiap format output, dan dalam imej kecil.
Nilai yang tersedia:
- assembled: Bahagian kekal di tempat asalnya seperti dalam model sumber.
- on_plate: Bahagian diletakkan rata dan direnggangkan di atas plat binaan, sedia untuk di-slice — susunan yang sama seperti paparan On Plate dalam aplikasi web.
Dalam kedua-dua susunan, cebisan yang runtuh atau bahagian seperti titik yang berbaki akibat pemotongan akan dialih keluar sebelum pengeksportan, jadi setiap bahagian yang anda terima boleh dicetak. Format yang menyokong objek adegan menyimpan satu objek bagi setiap bahagian; stl menggabungkannya menjadi satu pepejal tunggal.
Name
connectors
Type
boolean
lalai false
Description
Menambah penyambung tanggam-dan-lubang (mortise-and-tenon) pada setiap titik potongan supaya bahagian yang dicetak dapat disambungkan bersama.

Hanya berlaku apabila connectors = true

Name
connector_type
Type
string
lalai cube
Description
Bentuk penyambung pada setiap permukaan potongan.
Nilai yang tersedia: cube, cylinder.
Name
connector_size
Type
number
lalai 0.5
Description
Saiz penyambung relatif kepada permukaan potongan.
Julat sah: 0.1 hingga 0.8.
Name
connector_height
Type
number
lalai 0.1
Description
Sejauh mana penyambung menonjol daripada permukaan potongan, relatif kepada permukaan potongan.
Julat sah: 0.1 hingga 0.8.

Nilai Pulangan

Sifat result bagi respons mengandungi id bagi tugas Auto Split yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Prompt tiada: prompt diperlukan apabila mode ialah by_parts atau by_color.
- Prompt tidak meminta sebarang pemisahan, atau terlalu banyak bahagian: by_parts / by_color menerima 1 hingga 10 bahagian yang dinamakan. Penerangan yang meminta model dikekalkan dalam satu bahagian, atau menamakan lebih daripada 10 bahagian, akan ditolak. Tiada caj dikenakan.
- Tugas input tidak disokong: input_task_id mesti merujuk kepada tugas yang berjaya daripada jenis yang disokong, dijana menggunakan Meshy 6 atau Meshy 7.
- Tiada imej rujukan: by_color memerlukan input yang dijana daripada imej yang dimuat naik.
- Penyambung di luar julat: connector_size atau connector_height berada di luar julat 0.1 hingga 0.8.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk menjalankan tugas ini.
Name
404 - Not Found
Description
input_task_id tidak wujud atau bukan milik akaun anda.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Permintaan by_parts dan by_color juga berkongsi had penghuraian prompt sebanyak 12 permintaan seminit bagi setiap akaun.
Name
503 - Service Unavailable
Description
Pemisahan berasaskan prompt (by_parts dan by_color) buat sementara waktu tidak tersedia. Cuba lagi kemudian, atau gunakan mode: "auto", yang tidak terjejas. Tiada caj dikenakan.

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

Dapatkan Semula Tugas Auto Split

Endpoint ini mendapatkan semula tugas Auto Split berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas Auto Split yang hendak didapatkan semula.

Pulangan

Objek Tugas Auto Split.

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

Padam Tugasan Auto Split

Endpoint ini memadam secara kekal tugasan Auto Split, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugasan Auto Split yang hendak dipadam.

Status Tugasan

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugasan itu akan terus berjalan. Kredit bagi tugasan yang telah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam keadaan akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa sebarang pemulangan kredit.

Pulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan berstatus 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

Endpoint ini membolehkan anda mendapatkan senarai tugasan Auto Split.

Parameter

Atribut pilihan

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan lalai kepada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Lalai kepada 10 item. Maksimum yang dibenarkan ialah 100 item; nilai yang lebih besar akan ditetapkan kepada 100.
Name
sort_by
Type
string
Description
Medan untuk disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Nilai Pulangan

Mengembalikan senarai berpenomboran halaman bagi 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

Strim Tugas Auto Split

endpoint ini menstrim kemas kini masa nyata untuk tugas Auto Split menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas Auto Split yang hendak distrim.

Pulangan

Memulangkan strim Objek Tugas Auto Split sebagai Server-Sent Events.

Setiap acara message membawa objek tugas penuh seperti yang dipulangkan oleh Dapatkan Tugas Auto Split, termasuk consumed_credits, cap masa dan prompt_ignored; semasa tugas berstatus PENDING atau IN_PROGRESS, medan yang berubah antara setiap bingkai ialah progress, status, started_at dan preceding_tasks, manakala model_urls, thumbnail_url dan part_count akan muncul sebaik sahaja ia mencapai status SUCCEEDED. Acara error pula hanya membawa status_code dan message, jadi semak nama acara terlebih dahulu sebelum membaca 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
}

The Auto Split Task Object

Tugas Auto Split hanya membawa sifat-sifat di bawah. Medan prompt penjanaan yang disertakan oleh objek tugas lain (name, object_prompt, texture_prompt dan sebagainya), model_url tunggal, dan texture_urls tidak pernah diisi untuk pemisahan dan tidak dikembalikan. Sifat yang diisi semasa tugas berjalan (thumbnail_url, model_urls, cap masa) sentiasa hadir, kosong sehingga ia mempunyai nilai, jadi set kunci tidak berubah antara PENDING dan SUCCEEDED.

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut. Walaupun kami menggunakan UUID k-sortable untuk id tugas sebagai butiran pelaksanaan, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas. Nilainya ialah print-split.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk model yang dipisahkan, satu untuk setiap format yang diminta. Format yang menyokong objek adegan mengekalkan setiap bahagian sebagai objek berasingan; stl mencantumkannya menjadi satu pepejal. Sifat untuk sesuatu format akan ditinggalkan jika format tersebut tidak diminta.
- Name
  glb
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format GLB.
- Name
  obj
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format OBJ.
- Name
  fbx
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format FBX.
- Name
  stl
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format STL. Semua bahagian dicantumkan menjadi satu pepejal; minta 3mf untuk bahagian yang boleh dipilih secara berasingan.
- Name
  usdz
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format USDZ.
- Name
  blend
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format Blender.
- Name
  3mf
  Type
  string
  Description
  URL yang boleh dimuat turun untuk model yang dipisahkan dalam format 3MF.
Name
thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk pratonton model yang dipisahkan yang dirender, dengan setiap bahagian dalam warna yang berbeza, mengikut layout yang diminta.
Name
prompt_ignored
Type
boolean
Description
true apabila prompt bagi permintaan by_parts atau by_color tidak menamakan sebarang bahagian, jadi Meshy memisahkan model tersebut secara automatik sebaliknya — nama bahagian dalam hasil tersebut adalah milik Meshy, bukan milik anda. Hadir bermula dari PENDING. Ditinggalkan untuk tugas auto dan apabila prompt tersebut telah dipatuhi.
Name
part_count
Type
integer
Description
Bilangan bahagian yang boleh dicetak yang dihasilkan oleh pemisahan tersebut. Format yang menyokong objek adegan membawa satu objek bagi setiap bahagian; stl mencantumkannya menjadi satu pepejal, dan kiraan tersebut masih melaporkan bahagian-bahagian tersebut. Kepingan nipis yang runtuh yang tidak dapat diubah oleh segmentasi menjadi kepingan yang boleh dicetak dikeluarkan daripada fail sebelum eksport dan tidak dikira.
Name
progress
Type
integer
Description
Kemajuan tugas tersebut. Jika tugas belum bermula lagi, sifat ini akan menjadi 0. Sebaik sahaja tugas berjaya, ini akan menjadi 100.
Name
status
Type
string
Description
Status tugas tersebut. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului.
Nilai medan ini hanya bermakna jika status tugas tersebut ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas tersebut dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas tersebut dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas tersebut selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi 0.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error. Jika semakan keselamatan pembekal model menolak model input tersebut, tugas tersebut gagal dengan task_error.type invalid_input dan code provider_content_refused. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Sentiasa hadir: 10 sebaik sahaja tugas diterima, dan 0 untuk tugas FAILED kerana caj tersebut dikembalikan apabila gagal. Memadam tugas semasa ia masih PENDING juga mengembalikan kredit tersebut.

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
}