可打印性分析 API

通过测量 3D 模型的水密性、体积、孔洞、非流形边和退化面来检查该模型是否存在打印问题。你还可以按照计划打印的尺寸检查壁厚。

POST/openapi/v1/print/analyze

创建一个 Analyze Printability 任务

创建一个可打印性分析任务，用于评估一个 3D 模型并报告其可打印性指标。任务在后台运行。关于任务通常需要多长时间，请参阅处理时间。

当 Meshy 已经拥有 input_task_id 任务的 printability 结果时，新任务会立即就绪。你第一次对它执行 GET 时就会返回结果。

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

参数

Name
input_task_id
Type
string
必选
Description
除非你发送 model_url，否则此项为必填。要分析其模型的任务的 ID。该任务的状态必须为 SUCCEEDED，且必须属于你本人，或属于你所在的某个 workspace。
它可以是以下任意一种任务类型，使用 Meshy 6 或更新版本，包括 Meshy 7：
可打印性修复任务同样适用。

Name
model_url
Type
string
必选
Description
除非你发送 input_task_id，否则此项为必填。要分析的模型，以公开 URL 或 Data URI 的形式提供。如果两者都发送，Meshy 会使用 input_task_id。
若以 http 或 https URL 形式提供，模型必须是 .glb、.gltf、.obj、.fbx 或 .stl 文件，且不超过 400 MB。Data URI 只能承载 base64 编码的 GLB（data:model/gltf-binary;base64,...）或 glTF（data:model/gltf+json;base64,...）文件，且不超过 100 MB。请将 .obj、.fbx 或 .stl 文件以 http 或 https URL 的形式发送。
超过 100 MB 的文件还必须遵循以下规则：
- GLB、glTF、FBX 或 OBJ 文件最多可有 10,000,000 个面。Meshy 以三角形计数面数，因此一个四边形计为 2 个面，被绘制多次的 mesh 每份副本都计为一次。
- FBX 文件必须是二进制 FBX 7.1 或更新版本。
- GLB 或 glTF 文件不得使用 Draco 压缩。
Meshy 下载 URL（assets.meshy.ai/…?Expires=…&Signature=…）是经过签名的，到其任务的 expires_at 时会失效。再次读取该任务不会使其续期。对于你用 Meshy 生成的模型，请改为发送 input_task_id，只要 Meshy 保留着源任务（参见资产保留期），该方式就能持续工作。若要在此之后继续使用该模型，请在 expires_at 之前下载它，并发送你自己保存的副本。

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

Name
printer_type
Type
string
Description
你计划使用的打印机。它决定了壁厚检查的最小壁厚。如果你发送了打印尺寸但未发送 printer_type，Meshy 会使用 fdm。
可用取值：
- fdm：熔丝（filament），最小壁厚 1.0 mm
- sla：光敏树脂（resin），最小壁厚 0.8 mm
- full_color：全彩，最小壁厚 2.0 mm
任何其他值都会返回 400。
Name
intended_print_height_mm
Type
number
Description
打印件的高度，以毫米为单位，范围从 1 到 1000。超出该范围的值会返回 400。请发送此参数或 intended_print_longest_side_mm，不要同时发送两者。
它仅对 GLB 输入有效。对于不是 .glb 文件的 model_url，请改为发送 intended_print_longest_side_mm。
Name
intended_print_longest_side_mm
Type
number
Description
打印件最长边的长度，以毫米为单位，范围从 1 到 1000。超出该范围的值会返回 400。它对所有输入格式均有效。

如果你发送了 printer_type 而未指定尺寸，Meshy 会使用以下打印尺寸：

.glb 文件或任意 input_task_id：高 150 mm
.stl 文件：文件自身的最长边，按毫米解读
.obj、.fbx 或 .gltf 文件：最长边 150 mm

对于使用其他单位的 STL 文件，请发送 intended_print_longest_side_mm。

Meshy 会将两种打印尺寸都四舍五入到最接近的毫米数。

返回内容

响应的 result 字段保存着新建的可打印性分析任务的 ID。

失败模式

Name
400 - Bad Request
Description
请求无法执行。错误消息会说明发现了什么问题。例如：
- Missing parameter：既没有发送 input_task_id，也没有发送 model_url。
- Invalid UUID：input_task_id 不是有效的 UUID。
- Invalid model URL：model_url 格式有误、使用了不受支持的协议，或文件扩展名不受支持。
- Model file too large：model_url 文件来自 http 或 https URL 且超过 400 MB，或作为 Data URI 超过 100 MB。
- Too many faces：model_url 文件是超过 100 MB 的 GLB、glTF、FBX 或 OBJ 文件，且面数超过 10,000,000。请减少面数后重新发送该文件。
- ASCII FBX over 100 MB：model_url 文件是超过 100 MB 的 ASCII FBX。请改为发送二进制 FBX 或 GLB。
- Unreadable model file：model_url 文件超过 100 MB，且 Meshy 无法读取其文件头。例如，它是经过 Draco 压缩的 GLB 或 glTF，或是早于 7.1 版本的二进制 FBX。
- Model header too complex：model_url 文件超过 100 MB，且其文件头中包含的 mesh、节点或记录数量过多，无法检查。请减少文件中的对象数量后重新发送。
- Model file can't be downloaded：model_url 返回了一个错误，最常见的原因是签名的 Meshy 下载 URL 已过期。再次读取该任务会返回相同的 URL，且过期时间相同。请发送你自己保存的文件副本，或在 Meshy 仍保留源任务期间发送 input_task_id。
- Task not succeeded：input_task_id 任务仍处于等待中、进行中或已失败状态。
- Invalid print size：intended_print_height_mm 或 intended_print_longest_side_mm 超出了 1 到 1000 的范围，或请求中同时包含了两者。
- Unknown printer type：printer_type 既不是 fdm，也不是 sla 或 full_color。
- Height on a non-GLB model：请求中包含 intended_print_height_mm，而 model_url 却不是 .glb 文件。请改为发送 intended_print_longest_side_mm。
- Can't size this model by height：按所请求的高度，或默认的 150 mm 计算，模型的最长边会超出 1 到 1,000 mm 的范围。当模型是扁平的，或 Meshy 无法确定其尺寸时，也会出现此情况。请改为发送 intended_print_longest_side_mm。对于 .glb 格式的 model_url 以及部分 input_task_id 任务，Meshy 只有在任务启动后才能发现这一点，此时任务会以 FAILED 结束。
- STL size unusable：请求中包含 printer_type 但未指定尺寸，且 Meshy 无法读取 .stl 文件自身的最长边，或该值超出 1 到 1,000 mm 的范围。请发送 intended_print_longest_side_mm。
请修正请求后重新发送。参见错误。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
403 - Forbidden
Description
input_task_id 是一个浮雕（bas-relief）模型，此 endpoint 无法分析该类型。消息内容为 This model type does not support this operation。请发送其他模型。
Name
404 - Not Found
Description
Meshy 找不到与 input_task_id 对应的可分析模型。例如：
- 该任务不存在、已被删除，或不属于你本人，也不属于你所在的任何 workspace。
- 该任务使用的模型早于 Meshy 6，或其类型不产生 3D 模型。
- 该任务的模型文件已不在存储中。
请检查 input_task_id 是否为受支持的任务类型，且属于你本人或你所在的某个 workspace，或者改为以 model_url 发送模型。
Name
429 - Too Many Requests
Description
你超出了速率限制，或待处理任务过多。请稍候后重试。参见速率限制。

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

获取可打印性分析任务

根据任务 ID 返回一个可打印性分析任务。

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
}

参数

Name
id
Type
path
Description
创建响应中的任务 ID。

返回值

可打印性分析任务对象。其 printability 字段在任务变为 SUCCEEDED 之前不会出现。当 Meshy 检查了壁厚时，printability 还会包含 intended_print 和 thin_walls。

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

删除可打印性分析任务

永久删除一个可打印性分析任务，包括其缓存的结果。删除操作无法撤销。

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

路径参数

Name
id
Type
path
Description
要删除的任务的 ID。

任务状态

删除处于 PENDING 状态的任务会退还创建该任务时所使用的积分。

处于 IN_PROGRESS 状态的任务无法删除。该请求会返回 409 Conflict，任务会继续运行。Meshy 不会为已经开始运行的任务退款，因此删除它会让你同时失去积分和结果。请等待任务进入 SUCCEEDED、FAILED 或 CANCELED 状态后再删除它。

删除处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务不会退还其积分。

返回值

任务删除成功时返回 200 OK；当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

GET/openapi/v1/print/analyze

获取 Analyze Printability 任务列表

返回您的可打印性分析任务列表。

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

参数

Name
page_num
Type
integer
默认值 1
Description
要返回的页码，从 1 开始。
Name
page_size
Type
integer
默认值 10
Description
每页任务数量，最多为 100。
Name
sort_by
Type
string
Description
排序方式。
可用值：
- +created_at：最早优先
- -created_at：最新优先

返回值

分页的可打印性分析任务对象列表。

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

流式获取可打印性分析任务

以服务器发送事件（SSE）的形式流式传输可打印性分析任务的更新。

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 following PENDING frame 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
path
Description
创建响应中返回的任务 ID。

以服务器发送事件形式返回的可打印性分析任务对象流。

每个事件都包含完整的任务对象，其结构与 Get endpoint 返回的相同。当任务处于 PENDING 或 IN_PROGRESS 状态时，其输出字段为空（null、[] 或 {}），且 finished_at 为 0。只有在任务变为 SUCCEEDED 之后，Meshy 才会发送 printability 字段。

可打印性分析任务对象

一个可打印性分析任务对象描述了对一个 3D 模型的一次分析。它保存了状态、进度，以及任务成功时的 printability 结果。

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
}

Name
id
Type
string
Description
任务 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
任务创建的时间，以 Unix 毫秒表示。
Name
started_at
Type
timestamp
Description
任务开始的时间，以 Unix 毫秒表示。任务开始前为 0。
Name
finished_at
Type
timestamp
Description
任务完成的时间，以 Unix 毫秒表示。任务完成前为 0。
Name
expires_at
Type
timestamp
Description
任务结果过期的时间，以 Unix 毫秒表示。任务完成前为 0。
Name
task_error
Type
object
Description
任务失败时的错误详情。如果任务未失败，则为 null。参见Errors。
- Name
  message
  Type
  string
  Description
  描述出了什么问题。
Name
printability
Type
object
Description
分析的结果。在任务达到 SUCCEEDED 状态之前不会出现。
- Name
  _version
  Type
  string
  Description
  printability 结果的模式版本。值为 v1。
- Name
  status
  Type
  string
  Description
  总体判定结果，为以下之一：
  
  healthy：没有错误也没有警告
  
  warning：至少有一个警告，且没有错误
  
  error：至少有一个错误
  
  unknown：Meshy 无法分析该模型
  
  当 Meshy 检查了壁厚时，该值取 mesh 检查结果与 thin_walls.status 中较差的一个。从最差到最好的顺序依次是 error、warning、unknown 和 healthy。
- Name
  issue_count
  Type
  integer
  Description
  问题总数，等于 error_count + warning_count。
- Name
  error_count
  Type
  integer
  Description
  错误级别问题的数量。Meshy 会在以下每种情况下计为一个错误：
  
  模型不是 watertight（水密）的，且孔洞数超过 8 个。
  
  模型的孔洞数超过 8 个。
  
  体积为零或更小。
  
  模型的非流形边超过 50 条。
  
  当 Meshy 检查了壁厚时，壁厚过薄（thin_walls.status 为 error）会再计为一个错误。
- Name
  warning_count
  Type
  integer
  Description
  警告级别问题的数量。Meshy 会在以下每种情况下计为一个警告：
  
  模型不是 watertight（水密）的，且孔洞数不超过 8 个。
  
  模型的孔洞数为 1 到 8 个。
  
  模型的非流形边为 1 到 50 条。
  
  模型存在退化面。
- 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
  壁厚检查所使用的打印机和尺寸。仅当 Meshy 检查了壁厚时才会出现。
  Name
  printer_type
  Type
  string
  Description
  打印机类型，fdm、sla 或 full_color。
  Name
  height_mm
  Type
  number
  Description
  当打印尺寸按高度设定时，打印高度，以毫米为单位。否则为 null。
  Name
  longest_side_mm
  Type
  number
  Description
  打印件最长边的长度，以毫米为单位。当打印尺寸按高度设定时，Meshy 会根据模型比例计算该值。
  Name
  wall_thickness_mm
  Type
  number
  Description
  printer_type 对应的最小壁厚，以毫米为单位。Meshy 会将比此更薄的墙体报告为过薄。
  Name
  dimensions_mm
  Type
  array
  Description
  打印件的 [宽度, 深度, 高度]，以毫米为单位。高度值可能与 height_mm 相差不到一毫米。当输入不是 GLB、或 Meshy 无法确定模型尺寸时，该值为 null。
- Name
  thin_walls
  Type
  object
  Description
  壁厚检查的结果。仅当 Meshy 检查了壁厚时才会出现。
  Name
  thin_area_ratio
  Type
  number
  Description
  表面厚度小于 intended_print.wall_thickness_mm 的部分所占的比例，范围从 0 到 1。当 Meshy 无法测量该模型时为 null。
  Name
  has_thin_walls
  Type
  boolean
  Description
  如果表面任意部分过薄，则为 true。仅尖锐的棱角就可能使其为 true，因此应使用 status 来判断是否需要加厚墙壁。当 Meshy 无法测量该模型时为 null。
  Name
  status
  Type
  string
  Description
  壁厚判定结果，为以下之一：
  
  healthy：过薄的表面占比不超过 5%。
  
  error：过薄的表面占比超过 5%。要加厚墙壁，请将此任务的 id 作为 input_task_id 发送给可打印性修复。如果此任务分析的是来自 model_url 的 .stl、.fbx 或 .gltf 文件，请改为将该文件作为 model_url 发送。
  
  unknown：Meshy 无法测量该模型。如果壁厚检查本身失败，任务将以 FAILED 结束。
- Name
  evaluated_at
  Type
  timestamp
  Description
  Meshy 计算该分析的时间，以 Unix 毫秒表示。
Name
consumed_credits
Type
integer
Description
任务消耗的积分数量。始终为 0，因为分析是免费的。