可打印性分析 API

分析 3D 模型的 printability——水密性、体积、孔洞、非流形边和退化面。此外，还可以选择在你计划打印的尺寸下检查壁厚。

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

此 endpoint 创建一个新的可打印性分析任务。该任务评估 3D 模型并报告其 printability 指标。

如果输入任务已经有缓存的 printability，返回的任务会立即处于就绪状态，对其发起的第一次 GET 请求将直接返回分析结果，而无需经过 worker 处理。

若还想检查计划打印尺寸下的壁厚，请发送 printer_type、打印尺寸，或两者都发送。结果会在 printability.thin_walls 中返回。检查壁厚耗时更长，因此即使模型之前已被分析过，该任务通常也不会立即就绪。

参数

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 会绕过扩展名检查）。

两个打印尺寸字段最多只能发送一个。如果发送 printer_type 而不带尺寸，默认尺寸为：

.glb 以及任意 input_task_id：高度 150 毫米。
.stl：文件自身的最长边，按毫米读取。对于使用其他单位的 STL，请发送 intended_print_longest_side_mm。
.obj、.fbx、.gltf：最长边 150 毫米。

Name
printer_type
Type
string
Description
您计划使用的打印机类型。它决定了壁厚检查所用的最小壁厚。当您发送打印尺寸而未指定此项时，默认值为 fdm。
可用值：
- fdm：线材（FDM），最小壁厚 1.0 毫米。
- sla：光敏树脂（SLA），最小壁厚 0.8 毫米。
- full_color：全彩，最小壁厚 2.0 毫米。
Name
intended_print_height_mm
Type
number
Description
打印件的高度，单位为毫米。范围：[1, 1000]。四舍五入到最接近的毫米整数。仅适用于 GLB 输入。
Name
intended_print_longest_side_mm
Type
number
Description
打印件最长边的长度，单位为毫米。范围：[1, 1000]。四舍五入到最接近的毫米整数。适用于所有输入格式。

返回值

响应的 result 属性包含新创建的可打印性分析任务的 id。

失败模式

Name
400 - Bad Request
Description
请求不可接受。常见原因：
- 缺少参数：既未提供 input_task_id，也未提供 model_url。
- UUID 无效：input_task_id 不是有效的 UUID。
- 模型 URL 无效：model_url 格式错误、使用了不受支持的协议，或文件扩展名不受支持。
- 模型文件过大：model_url 指向的内容超过 100 MB。
- 任务未成功：引用的任务仍处于待处理、进行中，或已失败。
- 打印尺寸无效：intended_print_height_mm 或 intended_print_longest_side_mm 超出 [1, 1000] 范围，或两者都被发送。
- 打印机类型未知：printer_type 不是 fdm、sla 或 full_color。
- 非 GLB 模型指定了高度：intended_print_height_mm 与非 .glb 的 model_url 一起发送。请改用 intended_print_longest_side_mm。
- 无法按高度为该模型定尺寸：在所请求的高度（或默认的 150 毫米）下，模型的最长边会超出 [1, 1000] 毫米范围，模型是扁平的，或者其尺寸无法确定。请改用 intended_print_longest_side_mm。对于 .glb 的 model_url 以及部分 input_task_id 任务，此问题只有在任务开始后才能发现，此时任务会以 FAILED 结束，而非返回此错误。
- STL 尺寸不可用：发送了 printer_type 但未指定尺寸，且该 .stl 自身的最长边无法读取或超出 [1, 1000] 毫米范围。请发送 intended_print_longest_side_mm。
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"
  }'

# Also check wall thickness for a 100 mm tall SLA print
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",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

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

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

获取可打印性分析任务

此 endpoint 根据 ID 获取一个可打印性分析任务。

参数

Name
id
Type
path
Description
要获取的可打印性分析任务的 ID。

返回值

可打印性分析任务对象。在任务达到 SUCCEEDED 状态之前，printability 字段为 null。当进行了壁厚检查时，printability 还会包含 intended_print 和 thin_walls。

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
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "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
}

The Analyze Printability Task Object

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
任务的进度。如果任务尚未开始，此属性将为 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：无法分析该模型。
  
  如果检查了壁厚，则此值为上述检查结果与 thin_walls.status 中较差的一个。从最差到最好依次为：error、warning、unknown、healthy。
- Name
  issue_count
  Type
  integer
  Description
  问题总数，等于 error_count + warning_count。
- Name
  error_count
  Type
  integer
  Description
  错误级别问题的数量。当模型不是水密的（not watertight）、具有非正体积，或存在非流形边时，会引发错误。如果检查了壁厚，壁厚过薄（thin_walls.status 为 error）的情况会额外计为一个错误。
- 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
  intended_print
  Type
  object
  Description
  壁厚检查所使用的打印机和尺寸。仅在检查了壁厚时才会出现。
  Name
  printer_type
  Type
  string
  Description
  fdm、sla 或 full_color。
  Name
  height_mm
  Type
  number
  Description
  如果打印件是按高度确定尺寸的，则为打印高度，单位为毫米。否则为 null。
  Name
  longest_side_mm
  Type
  number
  Description
  打印件最长边的长度，单位为毫米。当按高度确定尺寸时，它是根据模型的比例计算得出的。
  Name
  wall_thickness_mm
  Type
  number
  Description
  printer_type 所要求的最小壁厚，单位为毫米。薄于此值的壁将被报告为过薄。
  Name
  dimensions_mm
  Type
  array
  Description
  打印件的 [width, depth, height]，单位为毫米。高度可能与 height_mm 相差零点几毫米。如果输入不是 GLB，或者无法确定模型的尺寸，则为 null。
- Name
  thin_walls
  Type
  object
  Description
  壁厚检查结果。仅在检查了壁厚时才会出现。
  Name
  thin_area_ratio
  Type
  number
  Description
  表面中薄于 intended_print.wall_thickness_mm 的部分所占比例，范围从 0 到 1。如果无法测量模型，则为 null。
  Name
  has_thin_walls
  Type
  boolean
  Description
  如果表面的任何部分过薄，则为 true。仅尖锐的拐角就可能导致此值为真，因此应使用 status 来判断壁厚是否需要加厚。如果无法测量模型，则为 null。
  Name
  status
  Type
  string
  Description
  壁厚的判定结果。以下之一：
  
  healthy：表面中过薄的部分占比不超过 5%。
  
  error：表面中过薄的部分占比超过 5%。要加厚壁厚，请将此任务的 id 作为 input_task_id 传递给 Repair Printability（对于 .stl、.fbx 或 .gltf 的 model_url，请改为将文件作为 model_url 发送）。
  
  unknown：无法测量模型。如果壁厚检查本身失败，任务将以 FAILED 结束。
- 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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}