Auto Split API

Pisahkan 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 tertinggal akibat pemotongan sentiasa diperkukuh supaya setiap bahagian dicetak dengan padu.

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

POST/openapi/v1/print/split

Create an Auto Split Task

Endpoint ini mencipta tugasan Auto Split yang baharu. Tugasan ini memotong model daripada tugasan terdahulu 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 tugasan yang berjaya (SUCCEEDED) yang modelnya hendak dibahagikan. Jenis tugasan yang disokong: Imej ke 3D, Berbilang Imej ke 3D, Teks ke 3D (pratonton), Remesh, Tukar, dan Ubah saiz. Tugasan tersebut mesti berstatus 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) tidak disokong. Model bertekstur boleh diterima, dan teksturnya tidak dibawa masuk ke dalam hasil.

  • Name
    mode
    Type
    string
    lalai auto
    Description

    Cara model dibahagikan kepada bahagian-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 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. Sempadan kawasan warna diambil daripada imej sumber, bukan daripada tekstur model input. Untuk Berbilang Imej ke 3D, Auto Split menggunakan imej sumber yang pertama.
Hanya berlaku apabila mode = by_parts or by_color
  • Name
    prompt
    Type
    string
    Diperlukan
    Description

    Menerangkan bahagian-bahagian yang hendak dibahagikan, dalam apa jua 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. Menamakan satu bahagian sahaja juga boleh diterima: segala yang tidak anda namakan akan menjadi satu bahagian yang tinggal, jadi the head membahagikan model kepada kepala dan selebihnya, sama seperti dalam aplikasi web. Sehingga 600 aksara. Terdapat dua mod kegagalan: penerangan yang meminta supaya tiada pembahagian langsung, atau menamakan lebih daripada 10 bahagian, akan ditolak dengan 400 dan tiada caj dikenakan; penerangan yang langsung tidak dapat difahami oleh Meshy akan beralih kepada auto, tugasan tetap dijalankan dan dicaj, dan responsnya membawa prompt_ignored: true.

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

    Format untuk mengeksport model yang telah dibahagikan. 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 mendapatkan bahagian yang boleh dipilih secara berasingan dalam slicer). glb sentiasa dihasilkan dan dikembalikan dalam model_urls; senaraikan mana-mana format lain yang anda mahukan 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-bahagian kekal di tempat asal seperti dalam model sumber.
    • on_plate: Bahagian-bahagian diletakkan rata dan disusun terlerai di atas plat pembinaan, sedia untuk dihiris — susunan yang sama seperti paparan On Plate dalam aplikasi web.

    Dalam kedua-dua susunan, kepingan nipis yang runtuh atau bahagian seperti titik yang tinggal daripada satu potongan akan dialih keluar sebelum eksport, jadi setiap bahagian yang anda perolehi 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 tenon-dan-mortis pada setiap potongan supaya bahagian yang dicetak boleh dipasang 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 menganjur keluar daripada permukaan potongan, relatif kepada permukaan potongan.

    Julat sah: 0.1 hingga 0.8.

Returns

Sifat result bagi respons mengandungi id bagi tugasan Auto Split yang baharu 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 tidak menerangkan sebarang pembahagian, atau bahagian terlalu banyak: by_parts / by_color menerima 1 hingga 10 keping yang dinamakan. Penerangan yang meminta supaya model dikekalkan dalam satu keping, atau menamakan lebih daripada 10 bahagian, akan ditolak. Tiada caj dikenakan.
    • Tugasan input tidak disokong: input_task_id mesti merujuk kepada tugasan 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 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 tugasan ini.

  • Name
    404 - Not Found
    Description

    input_task_id tidak wujud atau tidak dimiliki oleh 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

    Pembahagian 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 Tugasan Auto Split

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugasan Auto Split yang hendak didapatkan semula.

Nilai Pulangan

Objek Tugasan 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 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.

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 tersebut terus berjalan. Kredit untuk tugasan yang sudah dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa 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 terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pulangan

Mengembalikan 200 OK jika 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 diklem 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.

Pulangan

Mengembalikan senarai bernomboran 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

Stream an Auto Split Task

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 akan distrim.

Nilai Pulangan

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

Setiap acara 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 adalah progress, status, started_at dan preceding_tasks, dan model_urls, thumbnail_url serta part_count muncul sebaik sahaja ia mencapai SUCCEEDED. Acara error hanya membawa status_code dan message, jadi lakukan percabangan berdasarkan nama acara 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 yang tunggal, dan texture_urls tidak pernah diisi untuk pemisahan (split) dan tidak dikembalikan. Sifat-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 mengikut-k (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 telah dipisah, satu bagi setiap format yang diminta. Format yang menyokong objek adegan mengekalkan setiap bahagian sebagai objek berasingan; stl menggabungkannya menjadi satu pepejal. Sifat untuk sesuatu format akan diketepikan jika format tersebut tidak diminta.

    • Name
      glb
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format GLB.

    • Name
      obj
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format OBJ.

    • Name
      fbx
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format FBX.

    • Name
      stl
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format STL. Semua bahagian digabungkan 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 telah dipisah dalam format USDZ.

    • Name
      blend
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format Blender.

    • Name
      3mf
      Type
      string
      Description

      URL yang boleh dimuat turun untuk model yang telah dipisah dalam format 3MF.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk pratonton model yang telah dipisah yang dirender, dengan setiap bahagian dalam warna yang berbeza, dalam 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 tersebut secara automatik sebaliknya — nama bahagian dalam hasil adalah kepunyaan Meshy, bukan kepunyaan anda. Hadir bermula dari PENDING. Diketepikan untuk tugas auto dan apabila prompt telah dipatuhi.

  • Name
    part_count
    Type
    integer
    Description

    Bilangan bahagian yang boleh dicetak yang dihasilkan oleh pemisahan. Format yang menyokong objek adegan membawa satu objek bagi setiap bahagian; stl menggabungkannya menjadi satu pepejal, dan kiraan masih melaporkan bilangan bahagian tersebut. Kepingan runtuh yang tidak dapat dijadikan bahagian yang boleh dicetak oleh proses segmentasi dibuang daripada fail sebelum eksport dan tidak dikira.

  • Name
    progress
    Type
    integer
    Description

    Progress bagi tugas. Jika tugas belum bermula lagi, sifat ini akan bernilai 0. Sebaik sahaja tugas berjaya, ini akan menjadi 100.

  • Name
    status
    Type
    string
    Description

    Status bagi 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 dicipta, dalam milisaat.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa bila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, sifat ini akan bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa bila tugas 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 kreditnya.

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
}