Auto Split API

將 3D 模型拆分為可分別列印的多個部件——可以自動拆分、依你指定的部件拆分，或依顏色區域拆分——並可選擇加入連接件；切割後留下的薄壁區域會始終獲得加固，以確保每個部件都能以實心方式列印。

Auto Split 目前僅支援未貼圖的模型。對於 Image to 3D 和 Multi-Image to 3D，請在產生輸入時將 should_texture 設為 false。帶貼圖的輸入將返回 400 錯誤並被拒絕。對貼圖模型的支援正在開發中。

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，而 model_urls、thumbnail_url、part_count 和 parts 則會在任務到達 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
}

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-可排序的 UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
任務的類型。此值為 print-split。
Name
model_urls
Type
object
Description
拆分模型的可下載 URL，每個請求的格式對應一個。檔案中每個部件都是一個獨立的物件。如果未請求某種格式，則對應該格式的屬性將被省略。
- Name
  glb
  Type
  string
  Description
  GLB 格式拆分模型的可下載 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 格式拆分模型的可下載 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 格式拆分模型的可下載 URL。
- Name
  usdz
  Type
  string
  Description
  USDZ 格式拆分模型的可下載 URL。
- Name
  blend
  Type
  string
  Description
  Blender 格式拆分模型的可下載 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 格式拆分模型的可下載 URL：每個部件對應一個物件，每個物件都位於自己的耗材槽位上，單位為毫米，縮放比例使最長邊為 150 毫米，並附帶 Bambu Studio 專案設定。
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
拆分模型中可列印部件的數量 —— 每個匯出檔案中的物件對應一個部件。分割過程中無法轉換為可列印部件的坍塌碎片，會在匯出前從檔案中移除，不計入此數量。
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。
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

List Auto Split Tasks

參數

可選屬性

回傳值

Request

Response

流式取得 Auto Split 任務

參數

回傳值

Request

Response Stream

Auto Split 任務物件

The Auto Split Task Object