Auto Split API

將一個 3D 模型拆分為可分別列印的多個部件——可以自動拆分、按你指定的部件拆分，或按顏色區域拆分——並可選擇添加連接件；拆分產生的薄弱區域會始終被加固，以確保每個部件都能列印得堅固耐用。

拆分結果不會保留輸入的 texture。 Auto Split 接受帶 texture 的輸入，因此你無需使用 should_texture: false 重新產生模型。它會重建切割後的部件，並為每個部件賦予一個純色頂點顏色；任何匯出格式都不會攜帶輸入的 texture 貼圖。

POST/openapi/v1/print/split

流式取得 Auto Split 任務

此端點使用 Server-Sent Events（SSE）以串流方式回傳 Auto Split 任務的即時更新。

參數

Name
id
Type
path
Description
要串流取得的 Auto Split 任務的唯一識別碼。

回傳

以 Server-Sent Events 的形式回傳 Auto Split 任務物件的資料流。

每個 message 事件都帶有與取得 Auto Split 任務回傳的完整任務物件相同的資料，包括 consumed_credits、時間戳記以及 prompt_ignored；當任務處於 PENDING 或 IN_PROGRESS 狀態時，各影格之間會變動的欄位是 progress、status、started_at 和 preceding_tasks，而一旦任務進入 SUCCEEDED 狀態，則會出現 model_urls、thumbnail_url 和 part_count。error 事件只帶有 status_code 和 message，因此在讀取 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
}

Auto Split 任務物件

Auto Split 任務只攜帶以下屬性。其他任務物件包含的生成提示欄位（name、object_prompt、texture_prompt 等）、單一的 model_url 以及 texture_urls，在拆分任務中永遠不會被填入，也不會被回傳。隨著任務執行而逐步填入的屬性（thumbnail_url、model_urls、各個時間戳）始終存在，在取得值之前為空，因此 PENDING 和 SUCCEEDED 之間的鍵集合不會改變。

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
任務的類型。此值為 print-split。
Name
model_urls
Type
object
Description
拆分後模型的可下載 URL，每種請求的格式各對應一個。支援場景物件的格式會將每個部件保留為單獨的物件；stl 會將它們融合為單一實體。如果未請求某個格式，則不會回傳該格式對應的屬性。
- Name
  glb
  Type
  string
  Description
  GLB 格式的拆分模型的可下載 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 格式的拆分模型的可下載 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 格式的拆分模型的可下載 URL。
- Name
  stl
  Type
  string
  Description
  STL 格式的拆分模型的可下載 URL。所有部件都會融合為單一實體；如需可單獨選擇的部件，請使用 3mf。
- Name
  usdz
  Type
  string
  Description
  USDZ 格式的拆分模型的可下載 URL。
- Name
  blend
  Type
  string
  Description
  Blender 格式的拆分模型的可下載 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 格式的拆分模型的可下載 URL。
Name
thumbnail_url
Type
string
Description
拆分模型的渲染預覽圖的可下載 URL，依照請求的 layout，每個部件以不同顏色顯示。
Name
prompt_ignored
Type
boolean
Description
當 by_parts 或 by_color 請求的 prompt 未指明任何部件名稱時為 true，此時 Meshy 會自動拆分模型——結果中的部件名稱來自 Meshy，而非你提供的內容。從 PENDING 階段起即存在。對於 auto 任務以及提示被遵循的情況，此欄位會被省略。
Name
part_count
Type
integer
Description
拆分產生的可列印部件數量。支援場景物件的格式每個部件對應一個物件；stl 會將它們融合為單一實體，但計數仍回報部件數量。分割過程中無法產生可列印部件的崩解碎片，會在匯出前從檔案中移除，不計入計數。
Name
progress
Type
integer
Description
任務的進度。如果任務尚未開始，此屬性為 0。一旦任務成功，此值將變為 100。
Name
status
Type
string
Description
任務的狀態。可能的取值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
preceding_tasks
Type
integer
Description
前置任務的數量。
只有當任務狀態為 PENDING 時，此欄位的值才有意義。
Name
created_at
Type
timestamp
Description
任務建立時間的時間戳，單位為毫秒。
Name
started_at
Type
timestamp
Description
任務開始時間的時間戳，單位為毫秒。如果任務尚未開始，此屬性為 0。
Name
finished_at
Type
timestamp
Description
任務完成時間的時間戳，單位為毫秒。如果任務尚未完成，此屬性為 0。
Name
task_error
Type
object
Description
失敗任務的錯誤詳情。完整的 task_error 物件參考請參閱 Errors。如果模型提供方的安全檢查拒絕了輸入模型，任務將以 task_error.type 為 invalid_input、code 為 provider_content_refused 而失敗。參閱 Errors。
Name
consumed_credits
Type
integer
Description
此任務消耗的積分數量。始終存在：任務一旦被接受即為 10，FAILED 任務則為 0，因為失敗時費用會被退還。在任務仍處於 PENDING 狀態時刪除它，同樣會退還費用。

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
}

Auto Split API

Create an Auto Split Task

參數

返回值

失敗模式

Request

Response

取得 Auto Split 任務

參數

回傳值

Request

Response

刪除一個 Auto Split 任務

路徑參數

任務狀態

回傳值

Request

Response

取得 Auto Split 任務列表

參數

可選屬性

回傳值

Request

Response

流式取得 Auto Split 任務

參數

回傳

Request

Response Stream

Auto Split 任務物件

The Auto Split Task Object