Auto Split API

將 3D 模型拆分為可個別列印的多個部件。Meshy 會自行選擇切割位置，或沿著你指定的部件或顏色區域進行切割，並可以加入連接件。Meshy 一律會對切割後留下的薄弱區域進行加固，以確保每個部件都能牢固地列印出來。

預設情況下，拆分後的模型不會保留輸入模型的 texture。 你可以拆分一個帶有 texture 的模型，因此不需要使用 should_texture: false 重新生成它。Meshy 會重建切割後的部件，並為每個部件賦予純色頂點顏色。若要在每個部件上保留 texture，請傳送 keep_texture: true。

POST/openapi/v1/print/split

建立一個 Auto Split 任務

建立一個 Auto Split 任務。該任務會將先前任務的模型切割成可以分別列印的多個部件。它會回傳切割後的模型，檔案中每個部件都作為獨立物件存在。

該任務在背景執行。關於任務通常需要多長時間，請參閱處理時間。

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, keep the texture, 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",
    "keep_texture": true,
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

參數

Name
input_task_id
Type
string
必選
Description
要切割其模型的任務 ID。該任務的狀態必須為 SUCCEEDED。以下任務類型可用：
- 影象生成 3D
- 多圖生成 3D
- 文字生成 3D，preview 或 refine 任務
- 重新貼圖
- 重構網格
- 格式轉換
- 尺寸調整
模型必須由 Meshy 6 或 Meshy 7 生成，即 ai_model 設定為 meshy-6-lite、meshy-6、meshy-7、meshy-7.1 或 latest。不支援 Smart Topology 模型（meshy-t2 和 meshy-t2.5）。對於 refine、重新貼圖、重構網格、格式轉換或尺寸調整任務，該規則適用於任務最初所依據的模型。由上傳模型建立的重新貼圖、重構網格、格式轉換或尺寸調整任務會回傳 400。
模型面數最多為 8,000,000。面數更多的模型會回傳 400。在這種情況下，請先對其執行重構網格任務，然後改為傳送該重構網格任務的 ID。
你可以切割帶貼圖的模型。要在各部件上保留其貼圖，請傳送 keep_texture: true。

Name
mode
Type
string
預設值 auto
Description
如何將模型劃分為多個部件。
可用值：
- auto：由 Meshy 選擇切割方式，並忽略 prompt。即使 prompt 超過 600 個字元，仍會回傳 400。
- by_parts：Meshy 按你在 prompt 中指定的結構部件進行切割，例如頭部、手臂和軀幹。
- by_color：Meshy 按你在 prompt 中指定的顏色區域進行切割。Meshy 會在來源圖像中查找這些區域，而不是在輸入模型的貼圖中查找。輸入模型必須是透過影象生成 3D 或多圖生成 3D 從上傳的圖像生成的。其他輸入會回傳 400。對於多圖生成 3D，Meshy 會使用第一張來源圖像。

僅當 mode = by_parts or by_color

Name
prompt
Type
string
必選
Description
要將模型拆分成的各個部件，可使用任意語言，最多 600 個字元。更長的文字會回傳 400，即使 mode 為 auto 時也是如此。
Meshy 會從 prompt 中讀取 1 到 10 個部件名稱，因此請直接命名各部件，而不要描述模型。例如，split into the figure and the base 或 head, torso, left arm, right arm, legs。你可以只命名單一部件。所有未命名的部分會合併成另外一個部件，因此 the head 會將模型拆分為頭部和其餘部分，與網頁應用程式中的行為一致。
要求不進行拆分，或命名超過 10 個部件的 prompt 會回傳 400，且 Meshy 不會就此請求扣除積分。
如果 Meshy 無法從 prompt 中讀取到任何部件名稱，它會改用該模型的參考圖像。它會按你選擇的 mode，沿著在該圖像中找到的部件進行切割。此時任務仍會執行，Meshy 仍會扣除積分，且該任務的 prompt_ignored 為 true。如果模型沒有參考圖像，或 Meshy 在其中找到的部件少於 2 個，請求將回傳 400，且 Meshy 不會就此請求扣除積分。

Name
target_formats
Type
array
預設值 ["glb"]
Description
要生成的檔案格式。Meshy 始終生成 glb 並在 model_urls 中回傳它，再加上你列出的其他格式。
可用值：
- glb
- obj
- fbx
- stl
- usdz
- blend
- 3mf
除 stl 外，每種格式都支援 scene 物件，並將每個部件儲存為單獨的物件。STL 檔案不能儲存獨立物件，因此 Meshy 會將這些部件融合為一個實體，按 layout 排列。要取得可以在切片軟體中分別選取的部件，請請求 3mf。
設定 keep_texture: true 時，以下格式會保留貼圖：
- glb、fbx、usdz 和 blend：貼圖包含在檔案中。
- obj：貼圖包含在 material 檔案中，model_urls 會在 mtl 下回傳該檔案。
- stl 和 3mf：檔案僅儲存 geometry，不包含貼圖。
Name
layout
Type
string
預設值 assembled
Description
Meshy 在每種檔案格式以及縮圖中排列各部件的方式。
可用值：
- assembled：Meshy 保持各部件在來源模型中的原有位置。
- on_plate：Meshy 將各部件平鋪並在列印平台上展開排列，便於直接切片。這與網頁應用程式中的 On Plate 視圖排列方式相同。
在這兩種 layout 下，Meshy 都會在匯出前移除切割產生的任何已坍縮的碎片或點狀碎片，因此你得到的每個部件都是可列印的。支援 scene 物件的格式會為每個部件儲存一個物件，而 stl 會將各部件融合為一個實體。
Name
keep_texture
Type
boolean
預設值 false
Description
是否在各部件上保留輸入模型的貼圖。true 會讓每個部件都帶有輸入模型的貼圖，任務會在 texture_urls 中回傳這些貼圖。false 則會讓每個部件呈現單一的頂點顏色。
設定為 true 時，任務耗時約為原來的兩倍，積分消耗不變。未貼圖的輸入模型，無論設定為 true 還是 false，其拆分方式相同。如果 Meshy 無法保留貼圖，任務會以錯誤代碼 textured_split_refused 失敗。請參閱錯誤。
Name
connectors
Type
boolean
預設值 false
Description
是否在每個切割處新增榫卯連接件，以便列印出的各部件能夠拼接在一起。

僅當 connectors = true

Name
connector_type
Type
string
預設值 cube
Description
連接件在每個切割面上的形狀，cube 或 cylinder。
Name
connector_size
Type
number
預設值 0.5
Description
連接件相對於切割面的大小，範圍為 0.1 到 0.8。超出此範圍的值會回傳 400，即使 connectors 為 false 時也是如此。
Name
connector_height
Type
number
預設值 0.1
Description
連接件相對於切割面凸出的程度，範圍為 0.1 到 0.8。超出此範圍的值會回傳 400，即使 connectors 為 false 時也是如此。

回傳值

回應的 result 欄位儲存新 Auto Split 任務的 ID。

失敗情形

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現的問題。例如：
- Missing prompt：mode 為 by_parts 或 by_color，但缺少 prompt。
- Prompt describes no split, or too many parts：prompt 要求保持模型為一個整體，或命名了超過 10 個部件。by_parts 和 by_color 接受 1 到 10 個指定名稱的部件。Meshy 不會就此請求扣除積分。
- Unsupported input task：input_task_id 不是受支援類型的成功任務，或並非由 Meshy 6 或 Meshy 7 生成。
- No reference image：mode 為 by_color，但輸入模型並非由上傳的圖像生成。
- Out-of-range connector：connector_size 或 connector_height 超出 0.1 到 0.8 的範圍。
修正請求後重新傳送。請參閱錯誤。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- Insufficient credits：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- Free plan：建立任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
Name
403 - Forbidden
Description
以下情形之一：
- 內容審核（moderation）攔截了該 prompt。訊息為 explicit content 或 prohibited content。修改 prompt 後重試。
- input_task_id 是一個浮雕模型，該端點無法對其進行拆分。訊息為 This model type does not support this operation。請傳送其他模型。
Name
404 - Not Found
Description
input_task_id 不存在，或不屬於你的帳戶。請檢查該 ID，並使用建立該任務的帳戶對應的 API 金鑰。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。請參閱速率限制。
by_parts 和 by_color 請求還共享一個每個帳戶每分鐘 12 次請求的 prompt 讀取限制。
Name
503 - Service Unavailable
Description
按 prompt 拆分（by_parts 和 by_color）暫時不可用。請稍後重試，或傳送 mode: "auto"，該模式仍可正常使用。Meshy 不會就此請求扣除積分。

GET/openapi/v1/print/split/:id

取得 Auto Split 任務

根據任務 ID 返回對應的 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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_metallic.png?Expires=***",
      "normal": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_normal.png?Expires=***",
      "roughness": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_roughness.png?Expires=***"
    }
  ],
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

參數

Name
id
Type
path
Description
建立回應中返回的任務 ID。

返回值

Auto Split 任務物件。

DELETE/openapi/v1/print/split/:id

刪除 Auto Split 任務

永久刪除一個 Auto Split 任務，包括其模型和資料。刪除操作無法復原。

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 keeps 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."
}

路徑參數

Name
id
Type
path
Description
要刪除的任務的 ID。

任務狀態

刪除處於 PENDING 狀態的任務，會退還你建立該任務時所使用的積分。

處於 IN_PROGRESS 狀態的任務無法被刪除。該請求會回傳 409 Conflict，任務會繼續執行。Meshy 不會為已經開始的任務退款，因此刪除它會讓你同時損失積分和結果。請等待任務進入 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

刪除處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務不會退還其積分。

回傳值

任務被刪除時回傳 200 OK；當任務處於 IN_PROGRESS 狀態時回傳 409 Conflict。

GET/openapi/v1/print/split

列出 Auto Split 任務

返回你的 Auto Split 任務列表。

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
  }
]

參數

Name
page_num
Type
integer
Description
要返回的頁碼。從 1 開始，預設為 1。
Name
page_size
Type
integer
Description
每頁返回的任務數量，最多為 100。預設為 10。Meshy 會將更大的值按 100 處理。
Name
sort_by
Type
string
Description
排序方式。
可用值：
- +created_at：最早的在前
- -created_at：最新的在前

一個分頁的 Auto Split 任務物件列表。

GET/openapi/v1/print/split/:id/stream

流式取得 Auto Split 任務

以伺服器發送事件（SSE）的形式串流傳輸 Auto Split 任務的更新。

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
}

參數

Name
id
Type
path
Description
建立回應中返回的任務 ID。

回傳值

以伺服器發送事件形式返回的 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 之前請先檢查事件名稱。

Auto Split 任務物件

Auto Split 任務物件描述了一次 3D 模型的拆分。它儲存了任務成功時的狀態、progress 和部件檔案。

它不包含其他任務物件的 prompt 欄位，例如 name、object_prompt 和 texture_prompt。它也沒有單一的 model_url。thumbnail_url、model_urls 以及時間戳會隨著任務執行而被填入。它們始終存在，在有值之前為空。

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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_metallic.png?Expires=***",
      "normal": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_normal.png?Expires=***",
      "roughness": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/texture_0_roughness.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
}

Name
id
Type
string
Description
任務 ID。請將其視為不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 print-split。
Name
model_urls
Type
object
Description
拆分模型的下載 URL，每個你請求的格式對應一個。你未請求的格式不會出現對應的鍵。支援場景物件的格式會將每個部件保留為單獨的物件，而 stl 會將所有部件融合成一個實體。
- Name
  glb
  Type
  string
  Description
  GLB 檔案。
- Name
  obj
  Type
  string
  Description
  OBJ 檔案。
- Name
  mtl
  Type
  string
  Description
  MTL 檔案。當 keep_texture 為 true 且輸入模型帶有紋理時，會隨 OBJ 檔案一同出現。
- Name
  fbx
  Type
  string
  Description
  FBX 檔案。
- Name
  stl
  Type
  string
  Description
  STL 檔案，所有部件會融合成一個實體。如果需要可單獨選擇的部件，請請求 3mf。
- Name
  usdz
  Type
  string
  Description
  USDZ 檔案。
- Name
  blend
  Type
  string
  Description
  Blender 檔案。
- Name
  3mf
  Type
  string
  Description
  3MF 檔案。
Name
thumbnail_url
Type
string
Description
拆分模型預覽圖的下載 URL，使用你請求的 layout。當部件保留紋理時，預覽圖會展示該紋理；否則，每個部件會有各自的顏色。
Name
texture_urls
Type
array
Description
拆分模型的紋理貼圖，是一個包含一個物件的陣列。所有部件共享這些貼圖。僅當 keep_texture 為 true 且輸入模型帶有紋理時才會出現。
- Name
  base_color
  Type
  string
  Description
  基礎顏色貼圖的下載 URL。
- Name
  metallic
  Type
  string
  Description
  金屬度貼圖的下載 URL。當輸入沒有金屬度貼圖時不存在。
- Name
  normal
  Type
  string
  Description
  法線貼圖的下載 URL。當輸入沒有法線貼圖時不存在。
- Name
  roughness
  Type
  string
  Description
  粗糙度貼圖的下載 URL。當輸入沒有粗糙度貼圖時不存在。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景版本（RGBA）的下載 URL。僅在任務成功後，且 Meshy 繪製了透明預覽圖時才會出現。
Name
prompt_ignored
Type
boolean
Description
Meshy 是否忽略了該 prompt。當 by_parts 或 by_color 請求中的 prompt 未指定任何部件名稱時，該值為 true，此時 Meshy 會自動拆分模型。結果中的部件名稱隨之由 Meshy 命名，而非你指定的名稱。從 PENDING 狀態起出現。對於 auto 任務，以及任何 Meshy 按 prompt 執行的情況，該欄位會被省略。
Name
part_count
Type
integer
Description
拆分產生的可列印部件數量。支援場景物件的格式中，每個部件對應一個物件。stl 會將部件融合成一個實體，但 part_count 仍會計入它們的數量。在匯出之前，Meshy 會移除無法成為可列印部件的塌陷碎片，且不計入這些碎片。
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
任務建立的時間，以 Unix 毫秒表示。
Name
started_at
Type
timestamp
Description
任務開始的時間，以 Unix 毫秒表示。在任務開始之前為 0。
Name
finished_at
Type
timestamp
Description
任務完成的時間，以 Unix 毫秒表示。在任務完成之前為 0。
Name
expires_at
Type
timestamp
Description
任務結果過期的時間，以 Unix 毫秒表示。在任務完成之前為 0。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。請參閱錯誤。
如果安全檢查拒絕了輸入模型，任務會失敗，task_error.type 被設為 invalid_input，task_error.code 被設為 provider_content_refused。請傳送其他模型。請參閱錯誤。
在 keep_texture: true 的情況下，如果 Meshy 無法保留紋理，任務會失敗，task_error.code 被設為 textured_split_refused。請參閱錯誤。
Name
consumed_credits
Type
integer
Description
任務消耗的積分數量。該欄位始終存在。Meshy 接受任務後該值為 10，FAILED 任務的值為 0，因為任務失敗時 Meshy 會退還積分。刪除 PENDING 任務同樣會退還積分。