可打印性修复 API

对 3D 模型做 FDM 可打印性修复——修复非流形边、退化面、孔洞等拓扑问题，使 mesh 可直接用于打印。

POST/openapi/v1/print/repair

创建可打印性修复任务

此端点创建一个新的可打印性修复任务。任务会对一个 3D 模型运行拓扑修复，并返回一个水密、可直接打印的版本。

输出格式与输入格式保持一致。如果通过 model_url 提交 .stl，响应中的 model_urls.stl 即为修复后的模型，其它格式字段为空字符串。input_task_id 路径始终读取源任务的 GLB，所以输出为 .glb。

参数

input_task_id 与 model_url 二选一。两者同时提供时，以 input_task_id 为准。

修复过程中会因几何变更而移除现有纹理。如需重新添加纹理，可对修复后的模型调用重新纹理 API。

Name
input_task_id
Type
string
Required
Description
你拥有且已成功完成的任务 ID。支持的任务类型：图像生成 3D、多图生成 3D、文本生成 3D、Remesh、Retexture。任务状态必须为 SUCCEEDED，且必须已经产出 GLB 资产。

Name
model_url
Type
string
Required
Description
待修复的 3D 模型 URL。支持格式：.glb、.stl、.obj。最大文件大小：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 或者已失败。
- 缺少 GLB：被引用的任务没有可供修复的 GLB 资产。
Name
401 - Unauthorized
Description
鉴权失败，请检查 API key。
Name
402 - Payment Required
Description
常见原因：
- 免费计划：创建任务需要付费计划，请前往订阅页面升级。
- 积分不足：工作区的积分余额已用完。
Name
404 - Not Found
Description
被引用的任务不存在，或归属于其他用户。
Name
429 - Too Many Requests
Description
超出每用户的并发任务配额或速率限制。

请求

POST

/openapi/v1/print/repair

# 修复一个已存在的任务
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"
  }'

# 或者直接修复一个模型 URL
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"
  }'

响应

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

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

获取可打印性修复任务

此端点通过任务 ID 获取一个可打印性修复任务。

参数

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

可打印性修复任务对象。在任务到达 SUCCEEDED 之前 model_urls 内容为空；只有匹配输入格式的字段会被填充。

请求

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

响应

{
  "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": "",
    "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

删除可打印性修复任务

此端点将永久删除一个可打印性修复任务及其修复结果。此操作不可逆。

路径参数

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

成功时返回 200 OK。

请求

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

响应

// 成功时返回 200 OK。

GET/openapi/v1/print/repair

可打印性修复任务列表

此端点允许您获取可打印性修复任务的列表。

参数

可选参数

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：按创建时间降序。

分页的可打印性修复任务对象列表。

请求

GET

/openapi/v1/print/repair

curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

响应

[
  {
    "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=***",
      "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

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

此端点通过 Server-Sent Events (SSE) 流式返回可打印性修复任务的实时进度更新。

参数

Name
id
Type
path
Description
要订阅的可打印性修复任务的唯一标识。

一组以 SSE 推送的可打印性修复任务对象。

在任务为 PENDING 或 IN_PROGRESS 时，推送中只包含必要的 progress 和 status 字段。model_urls 仅在任务到达 SUCCEEDED 时推送。

请求

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

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 状态推送事件示例。
// 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-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=***",
    "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-sortable UUID，但不建议对 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。详见错误。
- Name
  message
  Type
  string
  Description
  描述出错原因的错误消息。
Name
model_urls
Type
object
Description
修复后的 3D 模型下载链接。只有与输入格式匹配的字段会被填充，其它格式字段为空字符串。
- Name
  glb
  Type
  string
  Description
  修复后 GLB 的下载链接。在输入为 GLB 或使用 input_task_id 时填充。
- Name
  fbx
  Type
  string
  Description
  预留 FBX 字段。可打印性修复任务中始终为空字符串。
- Name
  obj
  Type
  string
  Description
  修复后 OBJ 的下载链接。在 model_url 上传 OBJ 时填充。
- Name
  stl
  Type
  string
  Description
  修复后 STL 的下载链接。在 model_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
texture_urls
Type
array
Description
始终为空数组。可打印性修复仅处理几何，不重新烘焙贴图。
Name
consumed_credits
Type
integer
Description
本次任务消耗的积分。SUCCEEDED 时为 10；FAILED 时为 0（失败会自动退款）。

可打印性修复任务对象

{
  "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=***",
    "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
}