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 potongan sentiasa diperkukuh supaya setiap bahagian dicetak secara pejal.

Auto Split pada masa ini hanya menyokong model tidak bertekstur. Untuk Imej ke 3D dan Berbilang Imej ke 3D, jana input dengan should_texture ditetapkan kepada false. Input yang bertekstur akan ditolak dengan 400.

POST/openapi/v1/print/split

Cipta Tugas Auto Split

Endpoint ini mencipta tugas Auto Split yang baharu. Tugas ini memotong model daripada tugas sebelumnya kepada bahagian-bahagian yang boleh dicetak secara berasingan dan mengembalikan model yang telah dibahagikan, dengan setiap bahagian sebagai objeknya sendiri di dalam fail.

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas yang berjaya yang modelnya hendak dipecahkan. Jenis tugas yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D (pratonton), Remesh, Tukar, dan Ubah saiz. Tugas tersebut mestilah berstatus SUCCEEDED, dan modelnya mesti dijana menggunakan Meshy 6 atau Meshy 7 (ai_model meshy-6, meshy-7, atau latest). Model low-poly dan Smart Topology (meshy-t2) tidak disokong.

Name
mode
Type
string
lalai auto
Description
Cara model dibahagikan kepada bahagian-bahagian.
Nilai yang tersedia:
- auto: Meshy memilih potongan. prompt diabaikan.
- by_parts: Potong mengikut bahagian struktur yang anda namakan dalam prompt, seperti kepala, lengan, dan badan.
- by_color: Potong mengikut kawasan warna yang anda namakan dalam prompt. Memerlukan input yang dijana daripada imej yang dimuat naik (Imej ke 3D atau Berbilang Imej ke 3D); input lain akan ditolak dengan 400.

Hanya berlaku apabila mode = by_parts or by_color

Name
prompt
Type
string
Diperlukan
Description
Menerangkan bahagian-bahagian untuk dipecahkan, dalam mana-mana bahasa. Meshy membaca 1 hingga 10 nama bahagian daripadanya, jadi namakan bahagian-bahagian tersebut dan bukannya menerangkan model — contohnya split into the figure and the base, atau head, torso, left arm, right arm, legs. Sehingga 600 aksara. Terdapat dua mod kegagalan: penerangan yang kelihatan seperti pemecahan tetapi hanya menamakan kurang daripada dua bahagian (contohnya split into individual parts) akan ditolak dengan 400 dan tiada caj dikenakan; penerangan yang langsung tidak dapat dibaca oleh Meshy akan kembali menggunakan auto, tugas tersebut tetap dijalankan dan dicaj, dan responsnya membawa prompt_ignored: true.

Name
target_formats
Type
array
lalai ["glb"]
Description
Format untuk mengeksport model yang dipecahkan. Setiap bahagian adalah objek berasingan dalam setiap format. glb sentiasa dihasilkan dan dikembalikan dalam model_urls; senaraikan mana-mana format lain yang anda mahukan sebagai tambahan.
Nilai yang tersedia: glb, obj, fbx, 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-bahagian kekal di tempat asalnya seperti dalam model sumber.
- on_plate: Bahagian-bahagian diletakkan rata dan disebarkan di atas plat binaan, sedia untuk dihiris — susunan yang sama seperti paparan On Plate dalam aplikasi web.
Dalam kedua-dua susunan, fail yang dieksport mengandungi satu objek bagi setiap bahagian dan tiada lagi: kepingan nipis yang runtuh atau bahagian seperti titik yang tinggal daripada potongan akan dialih keluar sebelum eksport, jadi setiap objek yang anda jumpa dalam fail tersebut boleh dicetak.
Name
connectors
Type
boolean
lalai false
Description
Menambah penyambung tanggam-dan-lubang (mortise-and-tenon) pada setiap potongan supaya bahagian yang dicetak boleh dicantumkan 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 memanjang dari permukaan potongan, relatif kepada permukaan potongan.
Julat sah: 0.1 hingga 0.8.

Nilai Pulangan

Ciri result bagi respons mengandungi id bagi tugas Auto Split yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Prompt tiada: prompt diperlukan apabila mode ialah by_parts atau by_color.
- Prompt menamakan kurang daripada dua bahagian: by_parts / by_color memerlukan sekurang-kurangnya dua kepingan yang dinamakan (contohnya head, torso, base); arahan umum seperti split into individual parts akan ditolak. Tiada caj dikenakan.
- Tugas input tidak disokong: input_task_id mesti merujuk kepada tugas yang berjaya bagi jenis yang disokong, dijana menggunakan Meshy 6 atau Meshy 7.
- Input bertekstur: Model input mempunyai texture. Buat masa ini hanya model tanpa texture yang disokong.
- Tiada imej rujukan: by_color memerlukan input yang dijana daripada imej yang dimuat naik.
- Format tidak disokong: target_formats mengandungi stl.
- 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 melaksanakan 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
Pemecahan berasaskan prompt (by_parts dan by_color) tidak tersedia buat sementara waktu. 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.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

Dapatkan Semula Tugas Auto Split

Endpoint ini mendapatkan semula tugas Auto Split mengikut IDnya.

Parameter

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

Nilai Pulangan

Objek Tugas Auto Split.

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

Padam Tugasan Auto Split

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

Parameter Laluan

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

Pulangan

Mengembalikan 200 OK apabila berjaya.

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

Senaraikan Tugas Auto Split

Endpoint ini membolehkan anda mendapatkan senarai tugas 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 dikekang kepada 100.
Name
sort_by
Type
string
Description
Medan untuk diisih mengikut. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan secara menaik.
- -created_at: Isih mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berhalaman Objek Tugas Auto Split.

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

Alirkan Tugas Auto Split

Endpoint ini mengalirkan 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 dialirkan.

Pemulangan

Mengembalikan aliran The Auto Split Task Objects sebagai Server-Sent Events.

Setiap peristiwa message membawa objek tugas penuh seperti yang dikembalikan oleh Retrieve an Auto Split Task, termasuk consumed_credits, cap masa dan prompt_ignored; semasa tugas berstatus PENDING atau IN_PROGRESS, medan yang berubah antara bingkai ialah progress, status, started_at dan preceding_tasks, manakala model_urls, thumbnail_url, part_count dan parts akan muncul sebaik sahaja ia mencapai SUCCEEDED. Peristiwa error hanya membawa status_code dan message, jadi buat percabangan berdasarkan nama peristiwa sebelum membaca 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
}

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. Walaupun kami menggunakan UUID yang boleh disusun-k 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 boleh muat turun untuk model yang dipisah, satu bagi setiap format yang diminta. Setiap bahagian adalah objek berasingan dalam fail tersebut. Sifat untuk sesuatu format akan ditinggalkan jika format itu tidak diminta.
- Name
  glb
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format GLB.
- Name
  obj
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format OBJ.
- Name
  fbx
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format FBX.
- Name
  usdz
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format USDZ.
- Name
  blend
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format Blender.
- Name
  3mf
  Type
  string
  Description
  URL boleh muat turun untuk model yang dipisah dalam format 3MF.
Name
thumbnail_url
Type
string
Description
URL boleh muat turun untuk pratonton yang dirender bagi model yang dipisah, 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 mana-mana bahagian, jadi Meshy memisahkan model itu secara automatik sebaliknya — nama bahagian dalam hasil tersebut adalah milik Meshy, bukan milik anda. Hadir bermula dari PENDING. Ditinggalkan untuk tugas auto dan pada bila-bila masa prompt itu dipatuhi.
Name
part_count
Type
integer
Description
Bilangan bahagian yang boleh dicetak dalam model yang dipisah — satu bagi setiap objek dalam fail yang dieksport. Kepingan runtuh yang tidak dapat dijadikan bahagian boleh cetak oleh segmentasi dikeluarkan daripada fail sebelum eksport dan tidak dikira.
Name
progress
Type
integer
Description
Progress bagi tugas tersebut. Jika tugas belum bermula lagi, sifat ini akan bernilai 0. Setelah tugas berjaya, ia akan menjadi 100.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas itu dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas itu bermula, dalam milisaat. Jika tugas belum bermula lagi, sifat ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas itu selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan bernilai 0.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
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 akan mengembalikan caj tersebut.

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
}