可打印性分析 API

分析 3D 模型的 FDM printability——水密性、体积、孔洞、非流形边和退化面。

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

检索一个可打印性分析任务

此 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。

返回值

成功时返回 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

此 endpoint 允许您检索可打印性分析任务的列表。

参数

可选属性

  • 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：按创建时间降序排序。

返回值

返回一个分页的 Analyze Printability Task 对象 列表。

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

    任务的进度。如果任务尚未开始，此属性为 0。一旦任务成功完成，此值将变为 100。

  • Name
    preceding_tasks
    Type
    integer
    Description

    排在前面的任务数量。

    仅当任务状态为 PENDING 时，此字段的值才有意义。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建时的 timestamp，以毫秒为单位。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始时的 timestamp，以毫秒为单位。如果任务尚未开始，此属性为 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成时的 timestamp，以毫秒为单位。如果任务尚未完成，此属性为 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果将从系统中过期的 timestamp，以毫秒为单位。如果任务尚未完成，则为 0。

  • Name
    task_error
    Type
    object
    Description

    如果任务失败，则为错误信息。如果任务未失败，此属性为 null。有关更多详细信息，请参阅 Errors。

    • Name
      message
      Type
      string
      Description

      描述出错原因的错误信息。

  • Name
    printability
    Type
    object
    Description

    printability 评估结果。在任务达到 SUCCEEDED 之前为 null。

    • Name
      _version
      Type
      string
      Description

      printability 结果的模式版本。当前为 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

      计算分析结果时的 timestamp，以自纪元起的毫秒数表示。

  • Name
    consumed_credits
    Type
    integer
    Description

    始终为 0。此 endpoint 是免费的。

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
}