可列印性分析 API

分析 3D 模型的 FDM 可列印性——水密性、體積、孔洞、非流形邊和退化面。

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

如果輸入任務已經存在快取的 printability 結果，回傳的任務會立即處於就緒狀態，對其執行的第一次 GET 請求將直接回傳分析結果，而無需經過 worker 處理。

參數

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。檔案大小上限為 100 MB。必須使用 http、https 或 data: URL（data URL 會略過副檔名檢查）。

回傳值

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

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：既未提供 input_task_id 也未提供 model_url。
- 無效的 UUID：input_task_id 不是有效的 UUID。
- 無效的模型 URL：model_url 格式錯誤、使用了不支援的協定，或檔案副檔名不受支援。
- 模型檔案過大：model_url 指向的檔案體積超過 100 MB。
- 任務未成功：所引用的任務仍處於待處理、進行中或失敗狀態。
Name
401 - Unauthorized
Description
Authentication 失敗。請檢查您的 API key。
Name
403 - Forbidden
Description
該任務存在，但歸其他使用者所有。
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"
  }'

Response

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

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

檢索一個可列印性分析任務

此端點根據 ID 檢索一個可列印性分析任務。

參數

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

回傳

可列印性分析任務物件。在任務達到 SUCCEEDED 狀態之前，printability 欄位為 null。

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
}

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

刪除可列印性分析任務

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

路徑參數

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

回傳值

成功時回傳 200 OK。

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

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

List Analyze Printability Tasks

此端點允許您檢索可列印性分析任務的列表。

參數

可選屬性

Name
page_num
Type
integer
Description
用於分頁的頁碼。起始值和預設值均為 1。
Name
page_size
Type
integer
Description
每頁數量限制。預設為 10 項。最大允許為 50 項。
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 的形式回傳一個可列印性分析任務物件串流。

對於 PENDING 或 IN_PROGRESS 狀態的任務，回應串流將僅包含必要的 progress 和 status 欄位。printability 部分僅在任務達到 SUCCEEDED 狀態後才會傳送。

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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
}

Analyze Printability 任務物件

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作中使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
Analyze Printability 任務的類型。該值為 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
  可列印性結果的模式版本。目前為 v1。
- Name
  status
  Type
  string
  Description
  總體狀態。取值之一：
  
  healthy：沒有錯誤也沒有警告。
  
  warning：至少有一個警告，沒有錯誤。
  
  error：至少有一個錯誤。
  
  unknown：無法分析該模型。
- Name
  issue_count
  Type
  integer
  Description
  問題總數，等於 error_count + warning_count。
- Name
  error_count
  Type
  integer
  Description
  錯誤層級問題的數量。當模型不是水密的、具有非正體積或存在非流形邊時會產生錯誤。
- 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
  evaluated_at
  Type
  timestamp
  Description
  計算分析結果時的時間戳，以自紀元起算的毫秒數表示。
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
}