可列印性分析 API

對 3D 模型進行 FDM可列印性檢測——水密性、體積、孔洞、非流形邊、退化面。

POST/openapi/v1/print/analyze

建立可列印性分析任務

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

若被參照的任務已快取可列印性結果，回傳的任務在第一次 GET 時即可直接取得分析結果，不會再走 worker。

參數

input_task_id 與 model_url 擇一。兩者同時提供時，以 input_task_id 為準。

Name
input_task_id
Type
string
必選
Description
你擁有且已成功完成的任務 ID。支援的任務類型：圖片生成 3D、多圖生成 3D、文字生成 3D、重構網格、重新貼圖。任務必須使用 Meshy 6（或任意 Preview 模型），且狀態必須為 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。
- 任務尚未成功：被參照的任務仍為 pending、in progress 或已失敗。
Name
401 - Unauthorized
Description
驗證失敗，請檢查 API 金鑰。
Name
403 - Forbidden
Description
任務存在，但歸屬於其他使用者。
Name
404 - Not Found
Description
常見原因：
- 任務不存在或已被刪除。
- 任務使用的模型早於 Meshy 6，或任務模式不會產出 3D 資產。
- 底層模型檔案已無法使用。
Name
429 - Too Many Requests
Description
超出每位使用者的並行任務配額或速率限制。

请求

POST

/openapi/v1/print/analyze

# 分析一个已存在的任务
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"
  }'

# 或者直接分析一个模型 URL
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"
  }'

响应

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

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

取得可列印性分析任務

此端點會透過任務 ID 取得可列印性分析任務。

參數

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

回傳

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

请求

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

响应

{
  "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

刪除可列印性分析任務

此端點會永久刪除一個可列印性分析任務及其快取的結果。此操作無法復原。

路徑參數

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

回傳

成功時回傳 200 OK。

请求

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

响应

// 成功时返回 200 OK。

GET/openapi/v1/print/analyze

可列印性分析任務清單

此端點可讓您取得可列印性分析任務的清單。

參數

選用參數

Name
page_num
Type
integer
Description
頁碼，從 1 開始，預設為 1。
Name
page_size
Type
integer
Description
每頁筆數。預設 10，最大 50。
Name
sort_by
Type
string
Description
排序欄位。可選值：
- +created_at：依建立時間升冪排序。
- -created_at：依建立時間降冪排序。

回傳

可列印性分析任務物件的分頁清單。

请求

GET

/openapi/v1/print/analyze

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

响应

[
  {
    "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

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

此端點透過 Server-Sent Events (SSE) 串流回傳可列印性分析任務的即時進度更新。

參數

Name
id
Type
path
Description
要串流傳輸的可列印性分析任務 ID。

回傳

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

對於 PENDING 或 IN_PROGRESS 狀態的任務，事件中只包含必要的 progress 與 status 欄位。printability 區塊只會在任務達到 SUCCEEDED 時傳送一次。

请求

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

响应流

// Error 事件示例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message 事件示例展示任务进度。
// 对 PENDING 或 IN_PROGRESS 任务，事件中不会包含全部字段。
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
string
Description
任務的唯一識別碼。我們使用 k-sortable UUID 作為實作細節，但不應對其格式做任何假設。
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
任務建立時間，毫秒時間戳。
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：無 error 也無 warning。
  
  warning：至少有一個 warning，無 error。
  
  error：至少有一個 error。
  
  unknown：模型無法被分析。
- Name
  issue_count
  Type
  integer
  Description
  問題總數，等於 error_count + warning_count。
- Name
  error_count
  Type
  integer
  Description
  error 等級的問題數。模型不水密、體積非正值或存在非流形邊時會觸發 error。
- Name
  warning_count
  Type
  integer
  Description
  warning 等級的問題數。模型存在退化面或孔洞時會觸發 warning。
- 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。此端點免費。

可打印性分析任务对象

{
  "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
}