可列印性分析 API

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

POST/openapi/v1/print/analyze

建立可列印性分析任務

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

如果輸入任務已經擁有快取的 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 asset。
    • 底層模型檔案在儲存空間中已不再可用。
  • 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

檢索可列印性分析任務

此 endpoint 用於根據 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。

任務狀態

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

已處於 IN_PROGRESS 狀態的任務無法刪除：請求會被 409 Conflict 拒絕，任務將繼續執行。工作程序已經開始處理的任務，其 credits 不可退還，因此在執行過程中刪除它會讓你同時損失 credits 和結果。請等待其達到 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。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.
// 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
}

可列印性分析任務物件

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。雖然我們在實作細節中使用 k-可排序的 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：模型無法被分析。
    • 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

      評估器回傳的原始 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
      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
}