Auto Split API

將一個 3D 模型拆分為多個可分別列印的部件——可以自動拆分，也可以按照你指定的部件拆分，或依顏色區域拆分——並可選擇加入連接件；切割後留下的薄弱區域一律會被強化，以確保每個部件都能被實心列印出來。

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

POST/openapi/v1/print/split

流式取得 Auto Split 任務

此 endpoint 使用 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，而 model_urls、thumbnail_url 和 part_count 會在任務達到 SUCCEEDED 狀態後出現。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
}

The Auto Split Task Object

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

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序的 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
任務的 progress。如果任務尚未開始，此屬性值為 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。
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

建立 Auto Split 任務

參數

回傳值

失敗情形

Request

Response

取得 Auto Split 任務

參數

回傳

Request

Response

刪除一個 Auto Split 任務

路徑參數

任務狀態

回傳值

Request

Response

取得 Auto Split 任務清單

參數

可選屬性

回傳值

Request

Response

流式取得 Auto Split 任務

參數

回傳

Request

Response Stream

The Auto Split Task Object

The Auto Split Task Object