可列印性修復 API
修復 3D 模型,使其可以直接用於列印。Meshy 會修復非流形邊、退化面、孔洞以及其他 topology 問題。你還可以針對計劃列印的尺寸,加厚過薄的壁厚。
建立可列印性修復任務
建立一個可列印性修復任務,該任務會修復 3D 模型的 topology 並回傳可直接用於列印的水密版本。任務在背景執行。關於任務通常需要多長時間,請參閱處理時間。
修復後的模型與輸入格式相同。例如,若 model_url 為 .stl 檔案,則 model_urls.stl 儲存修復後的 mesh,且 model_urls 不包含其他格式的鍵。使用 input_task_id 時,Meshy 始終修復來源任務的 GLB 檔案,因此輸出為 .glb 檔案。
由於 geometry 發生了變化,Meshy 在修復過程中會移除模型的 texture。如需重新加上 texture,請將修復後的模型傳送到 Retexture API。
Request
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
}'
# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/model.stl"
}'
# Also thicken walls that are too thin for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/repair \
-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,例如 Image to 3D、Multi-Image to 3D、Text to 3D、Remesh、Retexture 或可列印性分析任務。該任務必須是透過 API 建立、狀態為SUCCEEDED且帶有 GLB 模型的任務。若該可列印性分析任務檢查過壁厚,還會傳遞其印表機類型和尺寸。此後的修復操作會檢查壁厚並加厚薄壁,即使你兩者都未傳送。你傳送的
printer_type或列印尺寸會取代分析中的對應值。對來自model_url的.stl、.fbx或.gltf檔案所做的可列印性分析任務無法使用此功能,請改為將該檔案以model_url形式傳送。
- 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 只能承載不超過 100 MB 的 base64 GLB(data:model/gltf-binary;base64,...)或 glTF(data:model/gltf+json;base64,...)檔案。.obj、.fbx或.stl檔案請以http或httpsURL 形式傳送。超過 100 MB 的檔案還必須遵循以下規則:
- GLB、glTF、FBX 或 OBJ 檔案最多可包含 10,000,000 個面。Meshy 以三角形計算面數,因此一個四邊形計為 2 個面,被多次繪製的 mesh 每份副本計一次。
- FBX 檔案必須是 7.1 或更新版本的二進位 FBX。
- GLB 或 glTF 檔案不得使用 Draco 壓縮。
Meshy 下載 URL(
assets.meshy.ai/…?Expires=…&Signature=…)經過簽署,到其任務的expires_at時間後將失效。重新讀取任務不會使其續期。對於你用 Meshy 生成的模型,請改為傳送input_task_id,只要 Meshy 仍保留來源任務(參見資產保留期),該方式就一直有效。要在此之後繼續使用該模型,請在expires_at之前下載並傳送你自己儲存的副本。
- Name
- alpha_thumbnail
- Type
- boolean
- 預設值 false
- Description
是否同時渲染帶透明背景(RGBA)的預覽圖,取得任務時會在
alpha_thumbnail_url中回傳。thumbnail_url不會改變。
若還想在你計畫列印的尺寸下加厚過薄的壁,請傳送 printer_type、列印尺寸,或兩者都傳送。只有當超過 5% 的表面對該印表機來說過薄時,Meshy 才會加厚這些壁。修復後的模型保留其原始比例。如需縮放,請使用 Resize API,其尺寸單位為公尺,因此 100 mm 應寫作 0.1。
- Name
- printer_type
- Type
- string
- Description
你計畫使用的印表機。它設定了修復所針對的最小壁厚。若傳送列印尺寸但未傳送
printer_type,Meshy 會使用fdm,除非input_task_id中的可列印性分析任務提供了印表機資訊。可用取值:
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 輸入有效。若
model_url不是.glb檔案,請改為傳送intended_print_longest_side_mm。
- Name
- intended_print_longest_side_mm
- Type
- number
- Description
列印件最長邊的長度,單位為毫米,範圍從
1到1000。超出該範圍的值會回傳400。它對所有輸入格式均有效。
若傳送了 printer_type 但未指定尺寸,且 Meshy 未從可列印性分析任務中複用任何尺寸,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
請求無法執行。錯誤訊息會說明發現的具體問題。例如:
- 缺少參數:既未傳送
input_task_id也未傳送model_url。 - UUID 無效:
input_task_id不是有效的 UUID。 - 模型 URL 無效:
model_url格式錯誤、使用了不支援的協定,或檔案副檔名不受支援。 - 模型檔案過大:
model_url檔案來自http或httpsURL 時超過 400 MB,或作為 data URI 時超過 100 MB。 - 面數過多:
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,且 Meshy 無法讀取其檔案標頭。例如,它是經過 Draco 壓縮的 GLB 或 glTF,或者是早於 7.1 版本的二進位 FBX。 - 模型標頭資訊過於複雜:
model_url檔案超過 100 MB,其檔案標頭中包含的 mesh、節點或記錄數量過多,無法檢查。請減少檔案中的物件數量後重新傳送。 - 模型檔案無法下載:
model_url回傳了錯誤,最常見的原因是已簽署的 Meshy 下載 URL 已過期。再次讀取任務會回傳相同的 URL 和相同的過期時間。請傳送你自己儲存的檔案副本,或在 Meshy 仍保留來源任務期間傳送input_task_id。 - 任務未成功:
input_task_id對應的任務仍處於待處理、進行中或已失敗狀態。 - 缺少 GLB:
input_task_id對應的任務沒有可供修復的 GLB 模型。 - 列印尺寸無效:
intended_print_height_mm或intended_print_longest_side_mm超出了1到1000的範圍,或請求中同時包含了這兩個參數。 - 未知印表機類型:
printer_type既不是fdm、sla,也不是full_color。 - 對非 GLB 模型指定高度:請求中包含
intended_print_height_mm,但model_url不是.glb檔案。請改為傳送intended_print_longest_side_mm。 - 無法按該高度為此模型定尺寸:在所請求的高度(或預設的 150 mm)下,模型最長邊會超出 1 到 1,000 mm 的範圍。當模型扁平,或 Meshy 無法確定其尺寸時也會發生此問題。請改為傳送
intended_print_longest_side_mm。對於.glb格式的model_url以及部分input_task_id任務,Meshy 只能在任務開始後才能發現此問題,此時任務會以FAILED狀態結束。 - STL 尺寸不可用:請求中包含
printer_type但未指定尺寸,且 Meshy 無法讀取.stl檔案自身的最長邊,或該值超出 1 到 1,000 mm 範圍。請傳送intended_print_longest_side_mm。
請修正請求後重新傳送。參見 Errors。
- 缺少參數:既未傳送
- Name
401 - Unauthorized- Description
API 金鑰缺失或無效。請檢查
Authorization請求標頭。
- Name
402 - Payment Required- Description
例如:
- 積分不足:帳戶沒有足夠的積分來執行此任務,或帳戶已達到積分限額。請檢查你的積分餘額,然後重試。
- 免費版方案:建立任務需要付費方案。請在訂閱設定中升級你的方案,然後重試。
- Name
403 - Forbidden- Description
input_task_id對應浮雕模型,此 endpoint 無法修復該類型模型。錯誤訊息為This model type does not support this operation。請傳送其他模型。
- Name
404 - Not Found- Description
input_task_id對應的任務不存在,或屬於其他使用者。請檢查該 ID,並使用建立該任務的帳戶對應的 API 金鑰。
- Name
429 - Too Many Requests- Description
你已超過速率限制,或待處理任務過多。請稍候後重試。參見速率限制。
獲取可列印性修復任務
透過 ID 返回一個可列印性修復任務。
Request
curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
Response (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000090000,
"expires_at": 1715725490000,
"task_error": null,
"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=***",
"texture_urls": [],
"consumed_credits": 10,
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"print_repair_report": {
"route": "thin_wall",
"applied": true,
"faces_before": 243112,
"faces_after": 251870,
"thin_area_ratio_before": 0.083,
"thin_area_ratio_after": 0.004
}
}
參數
- Name
- id
- Type
- path
- Description
建立回應中返回的任務 ID。
返回
可列印性修復任務物件。在任務變為 SUCCEEDED 之前,其 model_urls 欄位為空。此後,它只包含與輸入格式相符的那一個鍵。壁厚修復從一開始就包含 intended_print,任務成功後還會包含 print_repair_report。
刪除一個可列印性修復任務
永久刪除一個可列印性修復任務,包括其修復後的模型。刪除操作無法復原。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/print/repair/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。
取得可列印性修復任務清單
回傳您的可列印性修復任務清單。
Request
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"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=***",
"texture_urls": [],
"consumed_credits": 10
}
]
參數
- 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:最新優先
回傳值
一個分頁的可列印性修復任務物件清單。
流式取得可列印性修復任務
以 Server-Sent Events(SSE)的形式串流傳輸一個可列印性修復任務的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"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=***",
"texture_urls": [],
"consumed_credits": 10
}
參數
- Name
- id
- Type
- path
- Description
建立回應中返回的任務 ID。
回傳值
以 Server-Sent Events 形式回傳的可列印性修復任務物件串流。
每個事件都包含完整的任務物件,其結構與 Get endpoint 返回的一致。當任務處於
PENDING 或 IN_PROGRESS 狀態時,其輸出欄位為空
(null、[] 或 {}),且 finished_at 為 0。在任務狀態變為
SUCCEEDED 之前,model_urls 為空物件。
可列印性修復任務物件
可列印性修復任務物件描述一次 3D 模型的修復。它儲存了狀態、進度,以及任務成功後修復好的模型。
The Repair Printability Task Object
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"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=***",
"texture_urls": [],
"consumed_credits": 10
}
The Repair Printability Task Object (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000090000,
"expires_at": 1715725490000,
"task_error": null,
"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=***",
"texture_urls": [],
"consumed_credits": 10,
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"print_repair_report": {
"route": "thin_wall",
"applied": true,
"faces_before": 243112,
"faces_after": 251870,
"thin_area_ratio_before": 0.083,
"thin_area_ratio_after": 0.004
}
}
- Name
- id
- Type
- string
- Description
任務 ID。將其視為不透明字串,不要依賴其格式。
- Name
- type
- Type
- string
- Description
任務類型,始終為
print-repair。
- 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
- model_urls
- Type
- object
- Description
修復後模型的下載 URL。它只包含與輸入格式相符的鍵。 任務未生成的格式沒有對應的鍵,而不是空字串。
- Name
glb- Type
- string
- Description
修復後的 GLB 檔案。當輸入為 GLB 檔案,或你發送了
input_task_id時會設定該值。
- Name
gltf- Type
- string
- Description
修復後的 glTF 檔案。當輸入為 glTF 檔案時會設定該值。
- Name
fbx- Type
- string
- Description
修復後的 FBX 檔案。當輸入為 FBX 檔案時會設定該值。
- Name
obj- Type
- string
- Description
修復後的 OBJ 檔案。當輸入為 OBJ 檔案時會設定該值。
- Name
stl- Type
- string
- Description
修復後的 STL 檔案。當輸入為 STL 檔案時會設定該值。
- Name
- thumbnail_url
- Type
- string
- Description
修復後模型預覽圖的下載 URL。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
thumbnail_url的透明背景(RGBA)版本的下載 URL。僅當你在建立任務時發送了alpha_thumbnail: true,且 Meshy 繪製了透明預覽圖時才會出現。
- Name
- texture_urls
- Type
- array
- Description
始終為空陣列。修復只保留輸入的 geometry,不會重新烘焙貼圖。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數量。當任務為
SUCCEEDED時為10,當任務為FAILED時為0,因為 Meshy 會在任務失敗時退還積分。
- Name
- intended_print
- Type
- object
- Description
修復所使用的印表機和尺寸,無論是你發送的,還是 Meshy 從可列印性分析任務中複用的。對於壁厚修復,該欄位從一開始就存在,包括任務處於
PENDING狀態時。Meshy 尚不知道的值為null。- 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 會根據模型比例計算該值,在 Meshy 測量模型之前為
null。
- Name
wall_thickness_mm- Type
- number
- Description
printer_type對應的最小壁厚,以毫米為單位。
- Name
dimensions_mm- Type
- array
- Description
列印件的
[width, depth, height],以毫米為單位。高度值可能與height_mm相差零點幾毫米。在任務成功之前為null,對於非 GLB 的輸入也始終為null。
- Name
- print_repair_report
- Type
- object
- Description
壁厚修復執行的操作。壁厚修復成功後會出現該欄位。
- Name
route- Type
- string
- Description
實際執行的修復方式,取值之一:
thin_wall:超過 5% 的表面過薄,因此也執行了壁厚增厚。要查看是否修改了網格,請檢查applied。topology:壁厚已足夠,因此只執行了 topology 修復。topology_unmeasured:Meshy 無法測量壁厚,因此只執行了 topology 修復。
- Name
applied- Type
- boolean
- Description
壁厚增厚是否修改了網格。僅當
route為thin_wall時出現。
- Name
faces_before- Type
- integer
- Description
輸入網格的面數。僅當
route為thin_wall時出現。
- Name
faces_after- Type
- integer
- Description
修復後網格的面數。僅當
route為thin_wall時出現。
- Name
thin_area_ratio_before- Type
- number
- Description
輸入表面中比
intended_print.wall_thickness_mm更薄的部分所占比例,範圍從0到1。當 Meshy 無法測量輸入時省略該欄位。
- Name
thin_area_ratio_after- Type
- number
- Description
在修復後的模型上測得的相同比例。當無法測量時省略該欄位。任務仍然會成功。