可打印性修复 API

修复 3D 模型以实现 FDM printability——修复非流形边、退化面、孔洞及其他 topology 问题，使 mesh 达到可打印状态。

POST/openapi/v1/print/repair

创建可打印性修复任务

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

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

参数

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。该任务的状态必须为 SUCCEEDED，且必须已生成 GLB asset。

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 字段保持不变。

返回值

响应的 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 asset。
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"
  }'

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 字段会被填充。

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
}

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
任务创建时的时间戳，单位为毫秒。
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
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，不会重新烘焙贴图。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。任务达到 SUCCEEDED 后为 10。对于 FAILED 任务返回 0（失败时会退还 credits）。

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
}