Auto Split API

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

Auto Split 目前僅支援未貼圖的模型。對於影象生成 3D 和多圖生成 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.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
}

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，每種請求的格式對應一個。檔案中的每個部件都是一個獨立的物件。如果未請求某種格式，則該格式對應的屬性將被省略。
- 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。
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
此任務消耗的 credits 數量。此屬性始終存在：任務一旦被接受即為 10，而對於 FAILED 任務則為 0，因為失敗時費用會被退還。在任務仍處於 PENDING 狀態時刪除任務，同樣會退還費用。

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
}

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