可打印性修复 API

修复 3D 模型以提升 printability——修复非流形边、退化面、孔洞以及其他 topology 问题，使 mesh 达到可打印状态。此外，还可以选择在你计划打印的尺寸下，将过薄的壁进行加厚处理。

POST/openapi/v1/print/repair

Create a Repair Printability Task

此 endpoint 创建一个新的可打印性修复任务。该任务会对 3D 模型执行 topology 修复，并返回一个水密的、可直接打印的版本。

输出格式与输入格式一致。如果你通过 model_url 提交了一个 .stl 文件，响应中的 model_urls.stl 将保存修复后的 mesh，而其他格式字段将为空。input_task_id 路径始终读取源任务的 GLB，因此输出为 .glb。

若还想对按你计划打印尺寸来说过薄的壁进行加厚，请发送 printer_type、打印尺寸，或两者都发送。只有当超过 5% 的表面对该打印机来说过薄时，壁才会被加厚。修复后的模型保留其原始比例；可使用 Resize API 对其进行缩放，该接口使用米为单位（100 毫米即为 0.1）。

参数

input_task_id 或 model_url 中只需必填其中一个。如果两者都提供，则 input_task_id 的优先顺序更高。

由于 geometry 发生了变化，现有的 textures 会在修复过程中被移除。如需重新添加 textures，请对修复后的模型使用 Retexture API。

Name
input_task_id
Type
string
必选
Description
你拥有的一个已成功任务的 ID。支持的任务类型：Image to 3D、Multi-Image to 3D、Text to 3D、Remesh、Retexture 以及 Analyze Printability。该任务的状态必须为 SUCCEEDED，并且必须已生成 GLB 资产。
如果某个分析任务检查过壁厚，它也会传递其打印机和尺寸信息，因此即使你两者都未发送，修复任务也会检查壁厚并加厚过薄的壁；你所发送的 printer_type 或打印尺寸会覆盖该值。由 .stl、.fbx 或 .gltf 类型的 model_url 创建的分析任务不被接受：请改为将该文件作为 model_url 发送。

Name
model_url
Type
string
必选
Description
待修复的 3D 模型的 URL。支持的格式：.glb、.gltf、.obj、.fbx、.stl。最大文件大小：100 MB。必须使用 http、https 或 data: URL（data URL 会绕过扩展名检查）。

Name
alpha_thumbnail
Type
boolean
默认值 false
Description
设置为 true 时，任务会额外渲染一个透明背景（RGBA）版本的预览图，并在 GET 响应中以 alpha_thumbnail_url 返回。现有的 thumbnail_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，除非作为 input_task_id 的分析任务提供了打印机信息。
可用值：
- fdm：熔丝打印，最小壁厚 1.0 毫米。
- 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。
- 任务未成功：所引用的任务仍处于待处理、进行中，或已失败状态。
- 缺少 GLB：所引用的任务没有可供修复的 GLB 资产。
- 打印尺寸无效：intended_print_height_mm 或 intended_print_longest_side_mm 超出 [1, 1000] 范围，或两者都已发送。
- 打印机类型未知：printer_type 不是 fdm、sla 或 full_color。
- 非 GLB 模型指定了高度：对非 .glb 的 model_url 发送了 intended_print_height_mm。请改用 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
402 - Payment Required
Description
常见原因：
- 免费计划：创建任务需要付费计划。请在 subscription 页面升级。
- credits 不足：已达到 workspace 的 credit 上限。
Name
404 - Not Found
Description
所引用的任务不存在，或属于其他用户。
Name
429 - Too Many Requests
Description
你已超出待处理任务配额或速率限制。

Request

POST

/openapi/v1/print/repair

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

GET/openapi/v1/print/repair/:id

获取可打印性修复任务

此 endpoint 根据 ID 获取可打印性修复任务。

参数

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

返回值

可打印性修复任务对象。在任务达到 SUCCEEDED 状态之前，model_urls 块为空。仅会填充与输入格式匹配的 model_urls 字段。壁厚修复从一开始就包含 intended_print，任务成功后还会包含 print_repair_report。

Request

GET

/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "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=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "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
  }
}

DELETE/openapi/v1/print/repair/: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/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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 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/repair

获取可打印性修复任务列表

此 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/repair

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=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]

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

流式获取可打印性修复任务

此 endpoint 使用 Server-Sent Events (SSE) 流式传输可打印性修复任务的实时更新。

参数

Name
id
Type
path
Description
要流式传输的可打印性修复任务的唯一标识符。

以 Server-Sent Events 的形式返回一个可打印性修复任务对象流。

每一帧都携带该阶段的完整任务对象——与 Get endpoint 返回的结构相同——因此当任务处于 PENDING 或 IN_PROGRESS 状态时，输出字段尚未被填充（为 null、[] 或 {}），且 finished_at 为 null。model_urls 块仅在任务到达 SUCCEEDED 状态后才会发送。

Request

GET

/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

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 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-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=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

可打印性修复任务对象

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现中使用 k 可排序的 UUID 作为任务 id，但你不应对 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
任务创建时的 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
model_urls
Type
object
Description
修复后 3D 模型的可下载 URL。仅会填充与输入格式匹配的字段；其他格式字段均为空字符串。
- Name
  glb
  Type
  string
  Description
  修复后 GLB 的可下载 URL。当输入为 GLB 或使用了 input_task_id 时会填充此字段。
- Name
  gltf
  Type
  string
  Description
  修复后 GLTF 的可下载 URL。当输入为上传的 GLTF 时会填充此字段。
- Name
  fbx
  Type
  string
  Description
  修复后 FBX 的可下载 URL。当输入为上传的 FBX 时会填充此字段。
- Name
  obj
  Type
  string
  Description
  修复后 OBJ 的可下载 URL。当输入为上传的 OBJ 时会填充此字段。
- Name
  stl
  Type
  string
  Description
  修复后 STL 的可下载 URL。当输入为上传的 STL 时会填充此字段。
- Name
  usdz
  Type
  string
  Description
  为 USDZ 输出保留。对于可打印性修复任务，始终为空字符串。
- Name
  3mf
  Type
  string
  Description
  为 3MF 输出保留。对于可打印性修复任务，始终为空字符串。
- Name
  mtl
  Type
  string
  Description
  为 MTL 输出保留。对于可打印性修复任务，始终为空字符串。
Name
thumbnail_url
Type
string
Description
根据修复后的模型渲染出的预览图像的 URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景（RGBA）版本的可下载 URL。仅当任务创建时设置了 alpha_thumbnail: true 且透明预览渲染成功时才会出现；否则会省略此字段。
Name
texture_urls
Type
array
Description
始终为空数组。修复仅保留输入的 geometry，不会重新烘焙 texture。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。任务达到 SUCCEEDED 状态后为 10。对于 FAILED 任务返回 0（失败会退还 credits）。
Name
intended_print
Type
object
Description
修复所使用的打印机与尺寸，无论是本次发送的还是从分析任务中复用的。壁厚修复从一开始（PENDING）就会包含此字段；尚未知道的值为 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
  打印件最长边的长度，单位为毫米。当按高度确定尺寸时，此值根据模型的比例计算得出，在模型被测量之前为 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% 的表面过薄，因此也执行了壁厚增厚（见 applied）。
  
  topology：壁厚已足够；仅执行了 topology 修复。
  
  topology_unmeasured：无法测量壁厚；仅执行了 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。如果输入无法被测量，则省略此字段。
- Name
  thin_area_ratio_after
  Type
  number
  Description
  在修复后的模型上测得的相同比例。如果无法测量则省略；任务仍然会成功。

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=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "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=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "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
  }
}