可打印性分析 API
分析 3D 模型的 FDM printability——包括水密性、体积、孔洞、非流形边和退化面。
创建可打印性分析任务
此 endpoint 用于创建一个新的可打印性分析任务。该任务会评估一个 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
# 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"
}
检索可打印性分析任务
此 endpoint 用于根据 ID 检索一个可打印性分析任务。
参数
- Name
- id
- Type
- path
- Description
要检索的可打印性分析任务的 ID。
返回值
可打印性分析任务对象。在任务达到 SUCCEEDED 状态之前，printability 字段为 null。
Request
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
}
删除可打印性分析任务
此 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
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."
}
列出可打印性分析任务
此 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
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
}
]
流式获取可打印性分析任务
此 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
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
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
任务创建时的时间戳，单位为毫秒。
- 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
printability 评估结果。在任务达到
SUCCEEDED之前为null。- Name
_version- Type
- string
- Description
printability 结果的 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。此 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
}