可列印性修復 API

對 3D 模型進行 FDM可列印性修復——修復非流形邊、退化面、孔洞等拓樸問題，使網格可直接用於列印。

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
必選
Description
你擁有且已成功完成的任務 ID。支援的任務類型：圖像生成 3D、多圖生成 3D、文字生成 3D、重構網格、重新貼圖。任務狀態必須為 SUCCEEDED，且必須已產出 GLB 資產。

Name
model_url
Type
string
必選
Description
待修復的 3D 模型 URL。支援格式：.glb、.stl、.obj。最大檔案大小：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。
- 任務尚未成功：被引用的任務仍處於 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
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（失敗會自動退還）。

可打印性修复任务对象

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