可列印性分析 API
透過測量 3D 模型的水密性、體積、孔洞、非流形邊和退化面,來檢查該模型是否存在列印問題。你還可以依照預計列印的尺寸檢查壁厚。
建立一個 Analyze Printability 任務
建立一個可列印性分析任務,用於評估一個 3D 模型並報告其可列印性指標。任務在背景執行。關於任務通常需要多長時間,請參閱處理時間。
當 Meshy 已經擁有 input_task_id 任務的 printability 結果時,新任務會立即就緒。你第一次對它執行 GET 時就會返回結果。
Request
# 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"
}
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
除非你發送
model_url,否則此項為必填。要分析其模型的任務的 ID。該任務的狀態必須為SUCCEEDED,且必須屬於你本人,或屬於你所在的某個 workspace。它可以是以下任意一種任務類型,使用 Meshy 6 或更新版本,包括 Meshy 7:
可列印性修復任務同樣適用。
- Name
- model_url
- Type
- string
- 必選
- Description
除非你發送
input_task_id,否則此項為必填。要分析的模型,以公開 URL 或 Data URI 的形式提供。如果兩者都發送,Meshy 會使用input_task_id。若以
http或httpsURL 形式提供,模型必須是.glb、.gltf、.obj、.fbx或.stl檔案,且不超過 400 MB。Data URI 只能承載 base64 編碼的 GLB(data:model/gltf-binary;base64,...)或 glTF(data:model/gltf+json;base64,...)檔案,且不超過 100 MB。請將.obj、.fbx或.stl檔案以http或httpsURL 的形式發送。超過 100 MB 的檔案還必須遵循以下規則:
- GLB、glTF、FBX 或 OBJ 檔案最多可有 10,000,000 個面。Meshy 以三角形計數面數,因此一個四邊形計為 2 個面,被繪製多次的 mesh 每份副本都計為一次。
- FBX 檔案必須是二進位 FBX 7.1 或更新版本。
- GLB 或 glTF 檔案不得使用 Draco 壓縮。
Meshy 下載 URL(
assets.meshy.ai/…?Expires=…&Signature=…)是經過簽署的,到其任務的expires_at時會失效。再次讀取該任務不會使其續期。對於你用 Meshy 生成的模型,請改為發送input_task_id,只要 Meshy 保留著來源任務(參見資產保留期),該方式就能持續運作。若要在此之後繼續使用該模型,請在expires_at之前下載它,並發送你自己儲存的副本。
若還想按你計畫列印的尺寸檢查壁厚,請發送 printer_type、列印尺寸,或兩者都發送。結果會出現在 printability.thin_walls 中。檢查壁厚需要更長時間,因此即使 Meshy 之前已分析過該模型,任務通常也不會立即就緒。
- Name
- printer_type
- Type
- string
- Description
你計畫使用的印表機。它決定了壁厚檢查的最小壁厚。如果你發送了列印尺寸但未發送
printer_type,Meshy 會使用fdm。可用取值:
fdm:熔絲(filament),最小壁厚 1.0 mmsla:光敏樹脂(resin),最小壁厚 0.8 mmfull_color:全彩,最小壁厚 2.0 mm
任何其他值都會返回
400。
- Name
- intended_print_height_mm
- Type
- number
- Description
列印件的高度,以毫米為單位,範圍從
1到1000。超出該範圍的值會返回400。請發送此引數或intended_print_longest_side_mm,不要同時發送兩者。它僅對 GLB 輸入有效。對於不是
.glb檔案的model_url,請改為發送intended_print_longest_side_mm。
- Name
- intended_print_longest_side_mm
- Type
- number
- Description
列印件最長邊的長度,以毫米為單位,範圍從
1到1000。超出該範圍的值會返回400。它對所有輸入格式均有效。
如果你發送了 printer_type 而未指定尺寸,Meshy 會使用以下列印尺寸:
.glb檔案或任意input_task_id:高 150 mm.stl檔案:檔案自身的最長邊,按毫米解讀.obj、.fbx或.gltf檔案:最長邊 150 mm
對於使用其他單位的 STL 檔案,請發送 intended_print_longest_side_mm。
Meshy 會將兩種列印尺寸都四捨五入到最接近的毫米數。
返回內容
響應的 result 欄位保存著新建的可列印性分析任務的 ID。
失敗模式
- Name
400 - Bad Request- Description
請求無法執行。錯誤訊息會說明發現了什麼問題。例如:
- Missing parameter:既沒有發送
input_task_id,也沒有發送model_url。 - Invalid UUID:
input_task_id不是有效的 UUID。 - Invalid model URL:
model_url格式有誤、使用了不受支援的協定,或檔案副檔名不受支援。 - Model file too large:
model_url檔案來自http或httpsURL 且超過 400 MB,或作為 Data URI 超過 100 MB。 - Too many faces:
model_url檔案是超過 100 MB 的 GLB、glTF、FBX 或 OBJ 檔案,且面數超過 10,000,000。請減少面數後重新發送該檔案。 - ASCII FBX over 100 MB:
model_url檔案是超過 100 MB 的 ASCII FBX。請改為發送二進位 FBX 或 GLB。 - Unreadable model file:
model_url檔案超過 100 MB,且 Meshy 無法讀取其檔案標頭。例如,它是經過 Draco 壓縮的 GLB 或 glTF,或是早於 7.1 版本的二進位 FBX。 - Model header too complex:
model_url檔案超過 100 MB,且其檔案標頭中包含的 mesh、節點或記錄數量過多,無法檢查。請減少檔案中的物件數量後重新發送。 - Model file can't be downloaded:
model_url返回了一個錯誤,最常見的原因是已簽署的 Meshy 下載 URL 已過期。再次讀取該任務會返回相同的 URL,且過期時間相同。請發送你自己儲存的檔案副本,或在 Meshy 仍保留來源任務期間發送input_task_id。 - Task not succeeded:
input_task_id任務仍處於等待中、進行中或已失敗狀態。 - Invalid print size:
intended_print_height_mm或intended_print_longest_side_mm超出了1到1000的範圍,或請求中同時包含了兩者。 - Unknown printer type:
printer_type既不是fdm,也不是sla或full_color。 - Height on a non-GLB model:請求中包含
intended_print_height_mm,而model_url卻不是.glb檔案。請改為發送intended_print_longest_side_mm。 - Can't size this model by height:按所請求的高度,或預設的 150 mm 計算,模型的最長邊會超出 1 到 1,000 mm 的範圍。當模型是扁平的,或 Meshy 無法確定其尺寸時,也會出現此情況。請改為發送
intended_print_longest_side_mm。對於.glb格式的model_url以及部分input_task_id任務,Meshy 只有在任務啟動後才能發現這一點,此時任務會以FAILED結束。 - STL size unusable:請求中包含
printer_type但未指定尺寸,且 Meshy 無法讀取.stl檔案自身的最長邊,或該值超出 1 到 1,000 mm 的範圍。請發送intended_print_longest_side_mm。
請修正請求後重新發送。參見錯誤。
- Missing parameter:既沒有發送
- Name
401 - Unauthorized- Description
API 金鑰缺失或無效。請檢查
Authorization請求標頭。
- Name
403 - Forbidden- Description
input_task_id是一個浮雕(bas-relief)模型,此 endpoint 無法分析該類型。訊息內容為This model type does not support this operation。請發送其他模型。
- Name
404 - Not Found- Description
Meshy 找不到與
input_task_id對應的可分析模型。例如:- 該任務不存在、已被刪除,或不屬於你本人,也不屬於你所在的任何 workspace。
- 該任務使用的模型早於 Meshy 6,或其類型不產生 3D 模型。
- 該任務的模型檔案已不在儲存體中。
請檢查
input_task_id是否為受支援的任務類型,且屬於你本人或你所在的某個 workspace,或者改為以model_url發送模型。
- Name
429 - Too Many Requests- Description
你超出了速率限制,或待處理任務過多。請稍候後重試。參見速率限制。
取得可列印性分析任務
根據任務 ID 傳回一個可列印性分析任務。
Request
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
}
參數
- Name
- id
- Type
- path
- Description
建立回應中的任務 ID。
傳回值
可列印性分析任務物件。其 printability 欄位在任務變為 SUCCEEDED 之前不會出現。當 Meshy 檢查了壁厚時,printability 還會包含 intended_print 和 thin_walls。
刪除可列印性分析任務
永久刪除一個可列印性分析任務,包括其快取的結果。刪除操作無法復原。
Request
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 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。
取得 Analyze Printability 任務列表
返回您的可列印性分析任務列表。
Request
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
}
]
參數
- Name
- page_num
- Type
- integer
- 預設值 1
- Description
要返回的頁碼,從
1開始。
- Name
- page_size
- Type
- integer
- 預設值 10
- Description
每頁任務數量,最多為
100。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可用值:
+created_at:最早優先-created_at:最新優先
返回值
分頁的可列印性分析任務物件列表。
流式取得可列印性分析任務
以伺服器發送事件(SSE)的形式串流傳輸可列印性分析任務的更新。
Request
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 following PENDING frame 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
}
參數
- Name
- id
- Type
- path
- Description
建立回應中回傳的任務 ID。
回傳
以伺服器發送事件形式回傳的可列印性分析任務物件串流。
每個事件都包含完整的任務物件,其結構與 Get endpoint 回傳的相同。當任務處於
PENDING 或 IN_PROGRESS 狀態時,其輸出欄位為空(null、[] 或 {}),
且 finished_at 為 0。只有在任務變為 SUCCEEDED 之後,Meshy 才會發送
printability 欄位。
可列印性分析任務物件
一個可列印性分析任務物件描述了對一個 3D 模型的一次分析。它保存了狀態、progress,以及任務成功時的 printability 結果。
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
}
- Name
- id
- Type
- string
- Description
任務 ID。請將其視為一個不透明的字串,不要依賴其格式。
- Name
- type
- Type
- string
- Description
任務類型,始終為
print-analyze。
- Name
- status
- Type
- string
- Description
任務狀態,為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務完成的百分比。任務開始前為
0,成功後為100。
- 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
任務失敗時的錯誤詳情。如果任務未失敗,則為
null。參見錯誤。- Name
message- Type
- string
- Description
描述出了什麼問題。
- Name
- printability
- Type
- object
- Description
分析的結果。在任務達到
SUCCEEDED狀態之前不會出現。- Name
_version- Type
- string
- Description
printability 結果的結構版本。值為
v1。
- Name
status- Type
- string
- Description
整體判定結果,為以下之一:
healthy:沒有錯誤也沒有警告warning:至少有一個警告,且沒有錯誤error:至少有一個錯誤unknown:Meshy 無法分析該模型
當 Meshy 檢查了壁厚時,該值取 mesh 檢查結果與
thin_walls.status中較差的一個。從最差到最好的順序依次是error、warning、unknown和healthy。
- Name
issue_count- Type
- integer
- Description
問題總數,等於
error_count + warning_count。
- Name
error_count- Type
- integer
- Description
錯誤級別問題的數量。Meshy 會在以下每種情況下計為一個錯誤:
- 模型不是 watertight(水密)的,且孔洞數超過 8 個。
- 模型的孔洞數超過 8 個。
- 體積為零或更小。
- 模型的非流形邊超過 50 條。
當 Meshy 檢查了壁厚時,壁厚過薄(
thin_walls.status為error) 會再計為一個錯誤。
- Name
warning_count- Type
- integer
- Description
警告級別問題的數量。Meshy 會在以下每種情況下計為一個警告:
- 模型不是 watertight(水密)的,且孔洞數不超過 8 個。
- 模型的孔洞數為 1 到 8 個。
- 模型的非流形邊為 1 到 50 條。
- 模型存在退化面。
- Name
metrics- Type
- object
- Description
模型的原始 geometry 測量結果。
- Name
is_watertight- Type
- boolean
- Description
當 mesh 沒有邊界邊、即它是封閉的時為
true。
- Name
volume- Type
- number
- Description
模型的體積,以立方公尺為單位。
- Name
non_manifold_edges- Type
- integer
- Description
非流形邊的數量。
- Name
degenerate_faces- Type
- integer
- Description
退化面的數量,即面積為零或無效的面。
- Name
holes- Type
- integer
- Description
mesh 中孔洞的數量,按邊界環計數。
- Name
intended_print- Type
- object
- Description
壁厚檢查所使用的印表機和尺寸。僅當 Meshy 檢查了壁厚時才會出現。
- Name
printer_type- Type
- string
- Description
印表機類型,
fdm、sla或full_color。
- Name
height_mm- Type
- number
- Description
當列印尺寸按高度設定時,列印高度,以毫米為單位。否則為
null。
- Name
longest_side_mm- Type
- number
- Description
列印件最長邊的長度,以毫米為單位。當列印尺寸按高度設定時,Meshy 會根據模型比例計算該值。
- Name
wall_thickness_mm- Type
- number
- Description
printer_type對應的最小壁厚,以毫米為單位。Meshy 會將比此更薄的牆體報告為過薄。
- Name
dimensions_mm- Type
- array
- Description
列印件的
[寬度, 深度, 高度],以毫米為單位。高度值可能與height_mm相差不到一毫米。當輸入不是 GLB、或 Meshy 無法確定模型尺寸時,該值為null。
- Name
thin_walls- Type
- object
- Description
壁厚檢查的結果。僅當 Meshy 檢查了壁厚時才會出現。
- Name
thin_area_ratio- Type
- number
- Description
表面厚度小於
intended_print.wall_thickness_mm的部分所佔的比例,範圍從0到1。當 Meshy 無法測量該模型時為null。
- Name
has_thin_walls- Type
- boolean
- Description
如果表面任意部分過薄,則為
true。僅尖銳的稜角就可能使其為true,因此應使用status來判斷是否需要加厚牆壁。當 Meshy 無法測量該模型時為null。
- Name
status- Type
- string
- Description
壁厚判定結果,為以下之一:
healthy:過薄的表面佔比不超過 5%。error:過薄的表面佔比超過 5%。要加厚牆壁,請將此任務的id作為input_task_id傳送給可列印性修復。如果此任務分析的是來自model_url的.stl、.fbx或.gltf檔案,請改為將該檔案作為model_url傳送。unknown:Meshy 無法測量該模型。如果壁厚檢查本身失敗,任務將以FAILED結束。
- Name
evaluated_at- Type
- timestamp
- Description
Meshy 計算該分析的時間,以 Unix 毫秒表示。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數量。始終為
0,因為分析是免費的。