可打印性分析 API
对 3D 模型做 FDM 可打印性检测——水密性、体积、孔洞、非流形边、退化面。
创建可打印性分析任务
此端点创建一个新的可打印性分析任务。任务对一个 3D 模型进行评估，并返回其可打印性指标。
若被引用的任务已经缓存了可打印性结果，返回的任务在第一次 GET 时即可直接拿到分析结果，不会再走 worker。
参数
input_task_id 与 model_url 二选一。两者同时提供时，以 input_task_id 为准。
- Name
- model_url
- Type
- string
- Required
- 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 key。
- Name
403 - Forbidden- Description
任务存在，但归属于其他用户。
- Name
404 - Not Found- Description
常见原因：
- 任务不存在或已被删除。
- 任务使用的模型早于 Meshy 6，或者任务模式不会产出 3D 资产。
- 底层模型文件已不可用。
- Name
429 - Too Many Requests- Description
超出每用户的并发任务配额或速率限制。
请求
# 分析一个已存在的任务
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"
}
获取可打印性分析任务
此端点通过任务 ID 获取一个可打印性分析任务。
参数
- Name
- id
- Type
- path
- Description
要获取的可打印性分析任务的 ID。
返回
可打印性分析任务对象。printability 字段在任务到达 SUCCEEDED 之前为 null。
请求
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
}
删除可打印性分析任务
此端点将永久删除一个可打印性分析任务及其缓存的结果。此操作不可逆。
路径参数
- Name
- id
- Type
- path
- Description
要删除的可打印性分析任务的 ID。
返回
成功时返回 200 OK。
请求
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。
可打印性分析任务列表
此端点允许您获取可打印性分析任务的列表。
参数
可选参数
- 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：按创建时间降序。
返回
可打印性分析任务对象 的分页列表。
请求
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
}
]
流式获取可打印性分析任务
此端点通过 Server-Sent Events (SSE) 流式返回可打印性分析任务的实时进度更新。
参数
- Name
- id
- Type
- path
- Description
要 stream 的可打印性分析任务的 ID。
返回
以 Server-Sent Events 形式返回的 可打印性分析任务对象 流。
对于 PENDING 或 IN_PROGRESS 状态的任务，事件中只包含必要的 progress 与 status 字段。printability 块只在任务到达 SUCCEEDED 时发送一次。
请求
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。详见 Errors。- 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
}