可列印性分析 API

分析 3D 模型的可列印性——包括水密性、體積、孔洞、非流形邊緣和退化面。此外，還可以選擇在計劃列印的尺寸下檢查壁厚。

POST/openapi/v1/print/analyze

建立可列印性分析任務

此端點會建立一個新的可列印性分析任務。該任務會評估一個 3D 模型並回報其可列印性指標。

該任務在後台執行。關於通常所需的時間，請參見處理時間。

如果輸入任務已經快取了 printability 結果，回傳的任務會立即就緒，對其首次執行 GET 時將直接回傳分析結果，而不會經過 worker。

若還需按你計劃列印的尺寸檢查壁厚，請發送 printer_type、列印尺寸，或兩者都發送。結果會在 printability.thin_walls 中回傳。檢查壁厚耗時較長，因此即使該模型之前已經被分析過，該任務通常也不會立即就緒。

參數

input_task_id 和 model_url 中只有一個是必填的。如果兩者都提供，則 input_task_id 具有較高的優先順序。

Name
input_task_id
Type
string
必選
Description
你擁有的一個成功任務的 ID。支援的任務類型：Image to 3D、Multi-Image to 3D、Text to 3D、Remesh 和 Retexture。該任務必須使用 Meshy 6 或更新版本（包括 Meshy 7），且狀態必須為 SUCCEEDED。可列印性修復任務也可接受。

Name
model_url
Type
string
必選
Description
待分析的 3D 模型的 URL。支援的格式：.glb、.gltf、.obj、.fbx、.stl。請使用 http 或 https URL，或用於 GLB 的 base64 data: URL（data:model/gltf-binary;base64,...）或 glTF 的 base64 data: URL（data:model/gltf+json;base64,...）。.obj、.fbx 和 .stl 檔案必須以 http 或 https URL 的形式發送。
最大檔案大小：http 或 https URL 為 400 MB，data: URI 為 100 MB。
超過 100 MB 的 GLB、glTF、FBX 或 OBJ 檔案最多可包含 10,000,000 個面。面數按三角形計算：一個四邊形計為 2 個面，被多次繪製的 mesh 每份副本計一次。超過 100 MB 時，FBX 檔案必須是 7.1 或更新版本的二進位 FBX，且 GLB 或 glTF 檔案不得使用 Draco 壓縮。
Meshy 下載 URL（assets.meshy.ai/…?Expires=…&Signature=…）是經過簽署的，並會在任務的 expires_at 時失效；再次取得該任務並不會刷新這些連結。對於使用 Meshy 產生的模型，請改為傳入 input_task_id。只要來源任務仍處於保留狀態（見資產保留期），該方式就有效。若要在此之後重複使用模型，請在 expires_at 之前下載模型，並發送你自己儲存的副本。

兩個列印尺寸欄位最多只能發送一個。如果你在發送 printer_type 時未提供尺寸，預設尺寸為：

.glb 以及任何 input_task_id：高度 150 毫米。
.stl：檔案自身最長邊的尺寸，按毫米讀取。對於使用其他單位的 STL，請發送 intended_print_longest_side_mm。
.obj、.fbx、.gltf：最長邊 150 毫米。

Name
printer_type
Type
string
Description
你計劃使用的印表機類型。它決定了壁厚檢查所採用的最小壁厚。當你發送列印尺寸但未指定該項時，預設值為 fdm。
可用取值：
- fdm：線材列印，最小壁厚 1.0 毫米。
- sla：光敏樹脂，最小壁厚 0.8 毫米。
- full_color：全彩列印，最小壁厚 2.0 毫米。
Name
intended_print_height_mm
Type
number
Description
列印件的高度，單位為毫米。範圍：[1, 1000]。會四捨五入到最接近的毫米數。僅適用於 GLB 輸入。
Name
intended_print_longest_side_mm
Type
number
Description
列印件最長邊的長度，單位為毫米。範圍：[1, 1000]。會四捨五入到最接近的毫米數。適用於所有輸入格式。

回傳值

回應中的 result 屬性包含新建立的可列印性分析任務的 id。

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：未提供 input_task_id 或 model_url。
- UUID 無效：input_task_id 不是合法的 UUID。
- 模型 URL 無效：model_url 格式錯誤、使用了不受支援的通訊協定，或檔案副檔名不受支援。
- 模型檔案過大：model_url 的內容超過了 400 MB（http 或 https URL）或 100 MB（data: URI）。
- 面數過多：model_url 是大於 100 MB 的 GLB、glTF、FBX 或 OBJ 檔案，且面數超過 10,000,000。請減少面數後重新發送檔案。
- ASCII FBX 超過 100 MB：model_url 是超過 100 MB 的 ASCII FBX 檔案。請將其發送為二進位 FBX 或 GLB。
- 模型檔案無法讀取：model_url 超過 100 MB 且其檔頭無法讀取，例如經過 Draco 壓縮的 GLB 或 glTF，或早於 7.1 版本的二進位 FBX。
- 模型檔頭過於複雜：model_url 超過 100 MB，且其檔頭中包含的 mesh、節點或記錄數過多，無法檢查。請減少檔案中的物件數量後重新發送。
- 模型檔案無法下載：model_url 回傳了錯誤，最常見的原因是已簽署的 Meshy 下載 URL 已過期。再次取得該任務會回傳同一個帶有相同過期時間的 URL，因此請發送你自己儲存的檔案副本，或在來源任務仍處於保留狀態時使用 input_task_id。
- 任務未成功：所引用的任務仍處於等待中、進行中或已失敗狀態。
- 列印尺寸無效：intended_print_height_mm 或 intended_print_longest_side_mm 超出了 [1, 1000] 範圍，或兩者同時被發送。
- 印表機類型未知：printer_type 不是 fdm、sla 或 full_color。
- 非 GLB 模型指定了高度：對不是 .glb 的 model_url 發送了 intended_print_height_mm。請改用 intended_print_longest_side_mm。
- 無法按高度確定該模型尺寸：在所請求的高度（或預設的 150 毫米）下，模型最長邊會超出 [1, 1000] 毫米範圍、模型是扁平的，或其尺寸無法確定。請改用 intended_print_longest_side_mm。對於 .glb 格式的 model_url 以及部分 input_task_id 任務，此問題只有在任務開始後才能發現，此時任務會以 FAILED 結束，而不是回傳該錯誤。
- STL 尺寸不可用：發送了 printer_type 但未指定尺寸，且該 .stl 自身最長邊無法讀取或超出 [1, 1000] 毫米範圍。請發送 intended_print_longest_side_mm。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查你的 API 金鑰。
Name
404 - Not Found
Description
常見原因：
- 該任務不存在、已被刪除，或歸屬於其他使用者。
- 該任務使用的模型版本早於 Meshy 6，或其 mode 不會產生 3D 資產。
- 底層模型檔案在儲存體中已不再可用。
Name
429 - Too Many Requests
Description
你已超出待處理任務配額或速率限制。

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

# Also check wall thickness for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

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

GET/openapi/v1/print/analyze/:id

獲取可列印性分析任務

此 endpoint 根據 ID 獲取一個可列印性分析任務。

參數

Name
id
Type
path
Description
要獲取的可列印性分析任務的 ID。

返回值

可列印性分析任務物件。在任務達到 SUCCEEDED 狀態之前，printability 欄位為 null。當檢查了壁厚時，printability 還會包含 intended_print 和 thin_walls。

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

刪除可列印性分析任務

該 endpoint 會永久刪除一個可列印性分析任務及其快取結果。此操作不可復原。

路徑參數

Name
id
Type
path
Description
要刪除的可列印性分析任務的 ID。

任務狀態

仍處於 PENDING 狀態的任務會被刪除，並且建立時消耗的積分將被退還。

已處於 IN_PROGRESS 狀態的任務無法被刪除：請求會被拒絕並回傳 409 Conflict，任務會繼續執行。worker 已經開始處理的任務，其積分不可退還，因此在執行過程中將其刪除會導致你同時失去積分和結果。請等待任務到達 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務將被刪除，且不會退還積分。

回傳

成功時回傳 200 OK；當任務處於 IN_PROGRESS 狀態時回傳 409 Conflict。

Request

DELETE

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/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 is left 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."
}

GET/openapi/v1/print/analyze

列出可列印性分析任務

此 endpoint 允許您取得可列印性分析任務的清單。

參數

可選屬性

Name
page_num
Type
integer
Description
用於分頁的頁碼。起始值與預設值均為 1。
Name
page_size
Type
integer
Description
每頁數量限制。預設為 10 項。最大允許值為 100 項。
Name
sort_by
Type
string
Description
用於排序的欄位。可用值：
- +created_at：依建立時間升冪排序。
- -created_at：依建立時間降冪排序。

回傳

回傳一個分頁的可列印性分析任務物件清單。

Request

GET

/openapi/v1/print/analyze

curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

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

流式取得可列印性分析任務

此 endpoint 使用 Server-Sent Events (SSE) 以串流方式傳輸可列印性分析任務的即時更新。

參數

Name
id
Type
path
Description
要進行串流傳輸的可列印性分析任務的唯一識別碼。

回傳

以 Server-Sent Events 的形式回傳可列印性分析任務物件串流。

每一幀都攜帶該階段的完整任務物件——與 Get endpoint 回傳的結構相同——因此當任務處於 PENDING 或 IN_PROGRESS 狀態時，輸出欄位尚未被填入（為 null、[] 或 {}），且 finished_at 為 null。只有當任務到達 SUCCEEDED 狀態時，才會傳送 printability 區塊。

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作中使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
可列印性分析任務的類型。其值為 print-analyze。
Name
status
Type
string
Description
任務的狀態。可能的值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
progress
Type
integer
Description
任務的 progress。如果任務尚未開始，此屬性值為 0。一旦任務成功完成，此值將變為 100。
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
expires_at
Type
timestamp
Description
任務結果從系統中過期的時間的時間戳，以毫秒為單位。如果任務尚未完成，則為 0。
Name
task_error
Type
object
Description
如果任務失敗，此為錯誤資訊。如果任務未失敗，此屬性為 null。更多詳情請參閱錯誤。
- Name
  message
  Type
  string
  Description
  描述出錯原因的錯誤資訊。
Name
printability
Type
object
Description
可列印性評估結果。在任務達到 SUCCEEDED 之前為 null。
- Name
  _version
  Type
  string
  Description
  可列印性結果的 schema 版本。目前為 v1。
- Name
  status
  Type
  string
  Description
  整體狀態。取值為以下之一：
  
  healthy：無錯誤也無警告。
  
  warning：至少有一個警告，無錯誤。
  
  error：至少有一個錯誤。
  
  unknown：模型無法被分析。
  
  當進行了壁厚檢查時，此值為上述檢查結果與 thin_walls.status 中較差的一個。從最差到最好依序為：error、warning、unknown、healthy。
- Name
  issue_count
  Type
  integer
  Description
  問題的總數，等於 error_count + warning_count。
- Name
  error_count
  Type
  integer
  Description
  錯誤級別問題的數量。當模型非 watertight（不防水）、具有非正體積或存在非流形邊時會產生錯誤。當進行了壁厚檢查時，過薄的壁（thin_walls.status 為 error）會被額外計為一個錯誤。
- Name
  warning_count
  Type
  integer
  Description
  警告級別問題的數量。當模型包含退化面或孔洞時會產生警告。
- Name
  metrics
  Type
  object
  Description
  評估器傳回的原始幾何體指標。
  Name
  is_watertight
  Type
  boolean
  Description
  當網格沒有邊界邊（即是封閉的）時為 true。
  Name
  volume
  Type
  number
  Description
  模型體積，單位為立方公尺。
  Name
  non_manifold_edges
  Type
  integer
  Description
  非流形邊的數量。
  Name
  degenerate_faces
  Type
  integer
  Description
  退化面的數量（零面積或無效面）。
  Name
  holes
  Type
  integer
  Description
  網格中孔洞（邊界環）的數量。
- Name
  intended_print
  Type
  object
  Description
  壁厚檢查所使用的印表機類型和尺寸。僅當進行了壁厚檢查時才會存在。
  Name
  printer_type
  Type
  string
  Description
  fdm、sla 或 full_color。
  Name
  height_mm
  Type
  number
  Description
  如果列印件是依高度決定尺寸的，此為列印高度，單位為毫米。否則為 null。
  Name
  longest_side_mm
  Type
  number
  Description
  列印件最長邊的長度，單位為毫米。當依高度決定尺寸時，此值根據模型的比例計算得出。
  Name
  wall_thickness_mm
  Type
  number
  Description
  對應 printer_type 的最小壁厚，單位為毫米。比此值更薄的壁會被回報為過薄。
  Name
  dimensions_mm
  Type
  array
  Description
  列印件的 [width, depth, height]，單位為毫米。其中的高度值可能與 height_mm 相差零點幾毫米。對於非 GLB 輸入，或無法確定模型尺寸的情況，此值為 null。
- Name
  thin_walls
  Type
  object
  Description
  壁厚檢查的結果。僅當進行了壁厚檢查時才會存在。
  Name
  thin_area_ratio
  Type
  number
  Description
  表面中比 intended_print.wall_thickness_mm 更薄的部分所占比例，範圍從 0 到 1。如果無法測量模型，則為 null。
  Name
  has_thin_walls
  Type
  boolean
  Description
  如果表面任意部分過薄，則為 true。僅有尖銳邊角也可能觸發此值，因此應使用 status 來判斷壁是否需要加厚。如果無法測量模型，則為 null。
  Name
  status
  Type
  string
  Description
  壁厚的判定結果。取值為以下之一：
  
  healthy：表面中過薄部分占比不超過 5%。
  
  error：表面中過薄部分占比超過 5%。要加厚壁，請將此任務的 id 作為 input_task_id 傳遞給可列印性修復（對於 .stl、.fbx 或 .gltf 的 model_url，請改為將檔案作為 model_url 傳送）。
  
  unknown：無法測量模型。如果壁厚檢查本身失敗，任務將以 FAILED 結束。
- Name
  evaluated_at
  Type
  timestamp
  Description
  分析計算完成時間的時間戳，自 epoch 起以毫秒為單位。
Name
consumed_credits
Type
integer
Description
始終為 0。此端點是免費的。

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}