可打印性修复 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 发生变化，修复过程中会移除现有贴图。若要重新添加贴图，请在修复后的模型上使用 Retexture API。

Name
input_task_id
Type
string
必选
Description
你拥有的某个成功任务的 ID。支持的任务类型：Image to 3D、Multi-Image to 3D、Text to 3D、Remesh 和 Retexture。该任务的状态必须为 SUCCEEDED，且必须已生成 GLB 资产。

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 资产。
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。

返回值

成功时返回 200 OK。

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

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

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

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

参数

可选属性

Name
page_num
Type
integer
Description
用于分页的页码。起始值及默认值为 1。
Name
page_size
Type
integer
Description
每页数量限制。默认为 10 项，最大允许 50 项。
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 的形式返回可打印性修复任务对象流。

对于 PENDING 或 IN_PROGRESS 状态的任务，响应流将仅包含必要的 progress 和 status 字段。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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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-sortable 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
始终为空数组。修复仅保留输入的几何体，不会重新生成贴图。
Name
consumed_credits
Type
integer
Description
此任务消耗的积分数。一旦任务达到 SUCCEEDED 状态，值为 10。对于 FAILED 任务返回 0（失败时积分会被退还）。

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
}