可打印性修复 API
修复 3D 模型,使其可以直接用于打印。Meshy 会修复非流形边、退化面、孔洞以及其他 topology 问题。你还可以针对计划打印的尺寸,加厚过薄的壁厚。
创建可打印性修复任务
创建一个可打印性修复任务,该任务会修复 3D 模型的 topology 并返回可直接用于打印的水密版本。任务在后台运行。关于任务通常需要多长时间,请参阅处理时间。
修复后的模型与输入格式相同。例如,若 model_url 为 .stl 文件,则 model_urls.stl 保存修复后的 mesh,且 model_urls 不包含其他格式的键。使用 input_task_id 时,Meshy 始终修复源任务的 GLB 文件,因此输出为 .glb 文件。
由于 geometry 发生了变化,Meshy 在修复过程中会移除模型的 texture。如需重新添加 texture,请将修复后的模型发送到 Retexture API。
Request
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
}'
# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/model.stl"
}'
# Also thicken walls that are too thin for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/repair \
-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,例如 Image to 3D、Multi-Image to 3D、Text to 3D、Remesh、Retexture 或可打印性分析任务。该任务必须是通过 API 创建、状态为SUCCEEDED且带有 GLB 模型的任务。若该可打印性分析任务检查过壁厚,还会传递其打印机类型和尺寸。此后的修复操作会检查壁厚并加厚薄壁,即使你两者都未发送。你发送的
printer_type或打印尺寸会替换分析中的对应值。对来自model_url的.stl、.fbx或.gltf文件所做的可打印性分析任务无法使用此功能,请改为将该文件以model_url形式发送。
- Name
- model_url
- Type
- string
- 必选
- Description
除非发送
input_task_id,否则此项为必填。要修复的模型,可以是公开 URL 或 data URI。若两者都发送,Meshy 会使用input_task_id。若为
http或httpsURL,模型必须是.glb、.gltf、.obj、.fbx或.stl文件,且不超过 400 MB。Data URI 只能承载不超过 100 MB 的 base64 GLB(data:model/gltf-binary;base64,...)或 glTF(data:model/gltf+json;base64,...)文件。.obj、.fbx或.stl文件请以http或httpsURL 形式发送。超过 100 MB 的文件还必须遵循以下规则:
- GLB、glTF、FBX 或 OBJ 文件最多可包含 10,000,000 个面。Meshy 以三角形计数面数,因此一个四边形计为 2 个面,被多次绘制的 mesh 每份副本计一次。
- FBX 文件必须是 7.1 或更新版本的二进制 FBX。
- GLB 或 glTF 文件不得使用 Draco 压缩。
Meshy 下载 URL(
assets.meshy.ai/…?Expires=…&Signature=…)经过签名,到其任务的expires_at时间后将失效。重新读取任务不会使其续期。对于你用 Meshy 生成的模型,请改为发送input_task_id,只要 Meshy 仍保留源任务(参见资产保留期),该方式就一直有效。要在此之后继续使用该模型,请在expires_at之前下载并发送你自己保存的副本。
- Name
- alpha_thumbnail
- Type
- boolean
- 默认值 false
- Description
是否同时渲染带透明背景(RGBA)的预览图,获取任务时会在
alpha_thumbnail_url中返回。thumbnail_url不会改变。
若还想在你计划打印的尺寸下加厚过薄的壁,请发送 printer_type、打印尺寸,或两者都发送。只有当超过 5% 的表面对该打印机来说过薄时,Meshy 才会加厚这些壁。修复后的模型保留其原始比例。如需缩放,请使用 Resize API,其尺寸单位为米,因此 100 mm 应写作 0.1。
- Name
- printer_type
- Type
- string
- Description
你计划使用的打印机。它设定了修复所针对的最小壁厚。若发送打印尺寸但未发送
printer_type,Meshy 会使用fdm,除非input_task_id中的可打印性分析任务提供了打印机信息。可用取值:
fdm:熔丝(filament),最小壁厚 1.0 mmsla:光敏树脂(resin),最小壁厚 0.8 mmfull_color:全彩,最小壁厚 2.0 mm
任何其他取值都会返回
400。
- Name
- intended_print_height_mm
- Type
- number
- Description
打印高度,单位为毫米,范围从
1到1000。超出该范围的值会返回400。请发送此参数或intended_print_longest_side_mm之一,不要同时发送两者。该参数仅对 GLB 输入有效。若
model_url不是.glb文件,请改为发送intended_print_longest_side_mm。
- Name
- intended_print_longest_side_mm
- Type
- number
- Description
打印件最长边的长度,单位为毫米,范围从
1到1000。超出该范围的值会返回400。它对所有输入格式均有效。
若发送了 printer_type 但未指定尺寸,且 Meshy 未从可打印性分析任务中复用任何尺寸,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
请求无法执行。错误消息会说明发现的具体问题。例如:
- 缺少参数:既未发送
input_task_id也未发送model_url。 - UUID 无效:
input_task_id不是有效的 UUID。 - 模型 URL 无效:
model_url格式错误、使用了不支持的协议,或文件扩展名不受支持。 - 模型文件过大:
model_url文件来自http或httpsURL 时超过 400 MB,或作为 data URI 时超过 100 MB。 - 面数过多:
model_url文件是超过 100 MB 的 GLB、glTF、FBX 或 OBJ 文件,且面数超过 10,000,000。请减少面数后重新发送文件。 - ASCII FBX 超过 100 MB:
model_url文件是超过 100 MB 的 ASCII FBX。请以二进制 FBX 或 GLB 格式发送。 - 模型文件不可读:
model_url文件超过 100 MB,且 Meshy 无法读取其文件头。例如,它是经过 Draco 压缩的 GLB 或 glTF,或者是早于 7.1 版本的二进制 FBX。 - 模型头信息过于复杂:
model_url文件超过 100 MB,其文件头中包含的 mesh、节点或记录数量过多,无法检查。请减少文件中的对象数量后重新发送。 - 模型文件无法下载:
model_url返回了错误,最常见的原因是已签名的 Meshy 下载 URL 已过期。再次读取任务会返回相同的 URL 和相同的过期时间。请发送你自己保存的文件副本,或在 Meshy 仍保留源任务期间发送input_task_id。 - 任务未成功:
input_task_id对应的任务仍处于待处理、进行中或已失败状态。 - 缺少 GLB:
input_task_id对应的任务没有可供修复的 GLB 模型。 - 打印尺寸无效:
intended_print_height_mm或intended_print_longest_side_mm超出了1到1000的范围,或请求中同时包含了这两个参数。 - 未知打印机类型:
printer_type既不是fdm、sla,也不是full_color。 - 对非 GLB 模型指定高度:请求中包含
intended_print_height_mm,但model_url不是.glb文件。请改为发送intended_print_longest_side_mm。 - 无法按该高度为此模型定尺寸:在所请求的高度(或默认的 150 mm)下,模型最长边会超出 1 到 1,000 mm 的范围。当模型扁平,或 Meshy 无法确定其尺寸时也会发生此问题。请改为发送
intended_print_longest_side_mm。对于.glb格式的model_url以及部分input_task_id任务,Meshy 只能在任务开始后才能发现此问题,此时任务会以FAILED状态结束。 - STL 尺寸不可用:请求中包含
printer_type但未指定尺寸,且 Meshy 无法读取.stl文件自身的最长边,或该值超出 1 到 1,000 mm 范围。请发送intended_print_longest_side_mm。
请修正请求后重新发送。参见 Errors。
- 缺少参数:既未发送
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- 积分不足:账户没有足够的积分来执行此任务,或账户已达到积分限额。请检查你的积分余额,然后重试。
- 免费版计划:创建任务需要付费计划。请在订阅设置中升级你的计划,然后重试。
- Name
403 - Forbidden- Description
input_task_id对应浮雕模型,此 endpoint 无法修复该类型模型。错误消息为This model type does not support this operation。请发送其他模型。
- Name
404 - Not Found- Description
input_task_id对应的任务不存在,或属于其他用户。请检查该 ID,并使用创建该任务的账户对应的 API key。
- Name
429 - Too Many Requests- Description
你已超过速率限制,或待处理任务过多。请稍候后重试。参见速率限制。
获取可打印性修复任务
通过 ID 返回一个可打印性修复任务。
Request
curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
Response (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000090000,
"expires_at": 1715725490000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10,
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"print_repair_report": {
"route": "thin_wall",
"applied": true,
"faces_before": 243112,
"faces_after": 251870,
"thin_area_ratio_before": 0.083,
"thin_area_ratio_after": 0.004
}
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回
可打印性修复任务对象。在任务变为 SUCCEEDED 之前,其 model_urls 字段为空。此后,它只包含与输入格式匹配的那一个键。壁厚修复从一开始就包含 intended_print,任务成功后还会包含 print_repair_report。
删除一个可打印性修复任务
永久删除一个可打印性修复任务,包括其修复后的模型。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/print/repair/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。
获取可打印性修复任务列表
返回您的可打印性修复任务列表。
Request
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
]
参数
- 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:最新优先
返回值
一个分页的可打印性修复任务对象列表。
流式获取可打印性修复任务
以 Server-Sent Events(SSE)的形式流式传输一个可打印性修复任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
以 Server-Sent Events 形式返回的可打印性修复任务对象流。
每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的一致。当任务处于
PENDING 或 IN_PROGRESS 状态时,其输出字段为空
(null、[] 或 {}),且 finished_at 为 0。在任务状态变为
SUCCEEDED 之前,model_urls 为空对象。
可打印性修复任务对象
可打印性修复任务对象描述一次 3D 模型的修复。它保存了状态、进度,以及任务成功后修复好的模型。
The Repair Printability Task Object
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
The Repair Printability Task Object (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000090000,
"expires_at": 1715725490000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10,
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"print_repair_report": {
"route": "thin_wall",
"applied": true,
"faces_before": 243112,
"faces_after": 251870,
"thin_area_ratio_before": 0.083,
"thin_area_ratio_after": 0.004
}
}
- Name
- id
- Type
- string
- Description
任务 ID。将其视为不透明字符串,不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
print-repair。
- 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
- model_urls
- Type
- object
- Description
修复后模型的下载 URL。它只包含与输入格式匹配的键。 任务未生成的格式没有对应的键,而不是空字符串。
- Name
glb- Type
- string
- Description
修复后的 GLB 文件。当输入为 GLB 文件,或你发送了
input_task_id时会设置该值。
- Name
gltf- Type
- string
- Description
修复后的 glTF 文件。当输入为 glTF 文件时会设置该值。
- Name
fbx- Type
- string
- Description
修复后的 FBX 文件。当输入为 FBX 文件时会设置该值。
- Name
obj- Type
- string
- Description
修复后的 OBJ 文件。当输入为 OBJ 文件时会设置该值。
- Name
stl- Type
- string
- Description
修复后的 STL 文件。当输入为 STL 文件时会设置该值。
- Name
- thumbnail_url
- Type
- string
- Description
修复后模型预览图的下载 URL。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
thumbnail_url的透明背景(RGBA)版本的下载 URL。仅当你在创建任务时发送了alpha_thumbnail: true,且 Meshy 渲染了透明预览图时才会出现。
- Name
- texture_urls
- Type
- array
- Description
始终为空数组。修复只保留输入的 geometry,不会重新烘焙贴图。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量。当任务为
SUCCEEDED时为10,当任务为FAILED时为0,因为 Meshy 会在任务失败时退还积分。
- Name
- intended_print
- Type
- object
- Description
修复所使用的打印机和尺寸,无论是你发送的,还是 Meshy 从可打印性分析任务中复用的。对于壁厚修复,该字段从一开始就存在,包括任务处于
PENDING状态时。Meshy 尚不知道的值为null。- 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 会根据模型比例计算该值,在 Meshy 测量模型之前为
null。
- Name
wall_thickness_mm- Type
- number
- Description
printer_type对应的最小壁厚,以毫米为单位。
- Name
dimensions_mm- Type
- array
- Description
打印件的
[width, depth, height],以毫米为单位。高度值可能与height_mm相差零点几毫米。在任务成功之前为null,对于非 GLB 的输入也始终为null。
- Name
- print_repair_report
- Type
- object
- Description
壁厚修复执行的操作。壁厚修复成功后会出现该字段。
- Name
route- Type
- string
- Description
实际执行的修复方式,取值之一:
thin_wall:超过 5% 的表面过薄,因此也运行了壁厚增厚。要查看是否修改了 mesh,请检查applied。topology:壁厚已足够,因此只运行了 topology 修复。topology_unmeasured:Meshy 无法测量壁厚,因此只运行了 topology 修复。
- Name
applied- Type
- boolean
- Description
壁厚增厚是否修改了 mesh。仅当
route为thin_wall时出现。
- Name
faces_before- Type
- integer
- Description
输入 mesh 的面数。仅当
route为thin_wall时出现。
- Name
faces_after- Type
- integer
- Description
修复后 mesh 的面数。仅当
route为thin_wall时出现。
- Name
thin_area_ratio_before- Type
- number
- Description
输入表面中比
intended_print.wall_thickness_mm更薄的部分所占比例,范围从0到1。当 Meshy 无法测量输入时省略该字段。
- Name
thin_area_ratio_after- Type
- number
- Description
在修复后的模型上测得的相同比例。当无法测量时省略该字段。任务仍然会成功。