API Sửa khả năng in

Sửa mô hình 3D để đạt khả năng in FDM — khắc phục cạnh non-manifold, mặt suy biến, lỗ hổng và các vấn đề topology khác để lưới sẵn sàng để in.

POST/openapi/v1/print/repair

Tạo tác vụ Sửa khả năng in

Endpoint này tạo một tác vụ Sửa khả năng in mới. Tác vụ chạy sửa topology trên mô hình 3D và trả về một phiên bản kín nước, sẵn sàng để in.

Định dạng đầu ra khớp với định dạng đầu vào. Nếu bạn gửi một .stl qua model_url, model_urls.stl trong phản hồi sẽ chứa lưới đã sửa và các trường định dạng khác sẽ trống. Đường dẫn input_task_id luôn đọc GLB của tác vụ nguồn, vì vậy đầu ra là .glb.

Tham số

Chỉ một trong input_task_id hoặc model_url là bắt buộc. Nếu cả hai đều được cung cấp, input_task_id sẽ được ưu tiên.

Các texture hiện có sẽ bị xóa trong quá trình sửa do thay đổi hình học. Để thêm lại texture, hãy sử dụng API Tạo lại texture trên mô hình đã sửa.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ đã thành công mà bạn sở hữu. Các loại tác vụ được hỗ trợ: Ảnh sang 3D, Nhiều ảnh sang 3D, Văn bản sang 3D, Remesh, và Tạo lại texture. Tác vụ phải có trạng thái SUCCEEDED và phải đã tạo ra một asset GLB.

Name
model_url
Type
string
Bắt buộc
Description
URL của mô hình 3D cần sửa. Các định dạng được hỗ trợ: .glb, .stl, .obj. Kích thước tệp tối đa: 100 MB. Phải sử dụng URL http, https, hoặc data: (URL dữ liệu bỏ qua kiểm tra phần mở rộng).

Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi đặt thành true, tác vụ sẽ kết xuất thêm một phiên bản nền trong suốt (RGBA) của bản xem trước và trả về dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.

Trả về

Thuộc tính result của phản hồi chứa id của tác vụ Sửa khả năng in mới được tạo.

Các trường hợp lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Nguyên nhân phổ biến:
- Thiếu tham số: cả input_task_id lẫn model_url đều không được cung cấp.
- UUID không hợp lệ: input_task_id không phải là UUID hợp lệ.
- URL mô hình không hợp lệ: model_url bị sai định dạng, sử dụng scheme không được hỗ trợ, hoặc có phần mở rộng tệp không được hỗ trợ.
- Tệp mô hình quá lớn: nội dung model_url vượt quá 100 MB.
- Tác vụ chưa thành công: tác vụ được tham chiếu vẫn đang chờ, đang xử lý, hoặc đã thất bại.
- Thiếu GLB: tác vụ được tham chiếu không có asset GLB để sửa.
Name
401 - Unauthorized
Description
Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Nguyên nhân phổ biến:
- Gói miễn phí: việc tạo tác vụ yêu cầu gói trả phí. Nâng cấp tại trang đăng ký.
- Không đủ tín dụng: đã đạt đến giới hạn tín dụng của không gian làm việc.
Name
404 - Not Found
Description
Tác vụ được tham chiếu không tồn tại hoặc thuộc sở hữu của người dùng khác.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá hạn mức tác vụ đang chờ hoặc giới hạn tốc độ.

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

Truy xuất một tác vụ Sửa khả năng in

endpoint này truy xuất một tác vụ sửa khả năng in theo ID của nó.

Tham số

Name
id
Type
path
Description
ID của tác vụ sửa khả năng in cần truy xuất.

Trả về

Đối tượng tác vụ Sửa khả năng in. Khối model_urls sẽ trống cho đến khi tác vụ đạt SUCCEEDED. Chỉ trường model_urls khớp với định dạng đầu vào mới được điền.

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

Xóa tác vụ Sửa khả năng in

Endpoint này xóa vĩnh viễn một tác vụ sửa khả năng in và đầu ra đã được sửa của nó. Hành động này không thể đảo ngược.

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ sửa khả năng in cần xóa.

Trả về

Trả về 200 OK khi thành công.

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

Liệt kê các tác vụ Sửa khả năng in

endpoint này cho phép bạn truy xuất danh sách các tác vụ sửa khả năng in.

Tham số

Thuộc tính tùy chọn

Name
page_num
Type
integer
Description
Số trang cho phân trang. Bắt đầu và mặc định là 1.
Name
page_size
Type
integer
Description
Giới hạn kích thước trang. Mặc định là 10 mục. Tối đa được phép là 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp theo. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Trả về

Trả về danh sách được phân trang của Đối tượng tác vụ Sửa khả năng in.

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

Truyền phát tác vụ Sửa khả năng in

endpoint này truyền phát các cập nhật theo thời gian thực cho một tác vụ sửa khả năng in bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ sửa khả năng in cần truyền phát.

Trả về

Trả về một luồng Đối tượng tác vụ Sửa khả năng in dưới dạng Server-Sent Events.

Đối với các tác vụ PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết. Khối model_urls chỉ được gửi khi tác vụ đạt trạng thái 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=***",
    "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
}

Đối tượng tác vụ Sửa khả năng in

Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp k cho id tác vụ như một chi tiết triển khai, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại tác vụ sửa khả năng in. Giá trị là print-repair.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress của tác vụ. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa nếu trạng thái tác vụ là PENDING.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được bắt đầu, tính bằng mili giây. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi tác vụ hoàn tất, tính bằng mili giây. Nếu tác vụ chưa hoàn tất, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả tác vụ sẽ hết hạn khỏi hệ thống, tính bằng mili giây. 0 nếu tác vụ chưa hoàn tất.
Name
task_error
Type
object
Description
Thông tin lỗi nếu tác vụ thất bại. Thuộc tính này là null nếu tác vụ chưa thất bại. Xem Lỗi để biết thêm chi tiết.
- Name
  message
  Type
  string
  Description
  Thông báo lỗi mô tả điều gì đã xảy ra sai.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống đến mô hình 3D đã sửa. Chỉ trường khớp với định dạng đầu vào được điền; các trường định dạng khác là chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống đến GLB đã sửa. Được điền khi đầu vào là GLB hoặc khi input_task_id được sử dụng.
- Name
  fbx
  Type
  string
  Description
  Dành riêng cho đầu ra FBX. Luôn là chuỗi rỗng đối với các tác vụ sửa khả năng in.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống đến OBJ đã sửa. Được điền khi đầu vào là bản tải lên OBJ.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống đến STL đã sửa. Được điền khi đầu vào là bản tải lên STL.
- Name
  usdz
  Type
  string
  Description
  Dành riêng cho đầu ra USDZ. Luôn là chuỗi rỗng đối với các tác vụ sửa khả năng in.
- Name
  3mf
  Type
  string
  Description
  Dành riêng cho đầu ra 3MF. Luôn là chuỗi rỗng đối với các tác vụ sửa khả năng in.
- Name
  mtl
  Type
  string
  Description
  Dành riêng cho đầu ra MTL. Luôn là chuỗi rỗng đối với các tác vụ sửa khả năng in.
Name
thumbnail_url
Type
string
Description
URL của hình ảnh xem trước được render từ mô hình đã sửa.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống đến phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi tác vụ được tạo với alpha_thumbnail: true và bản xem trước trong suốt đã được render thành công; nếu không, trường này sẽ bị bỏ qua.
Name
texture_urls
Type
array
Description
Luôn là một mảng rỗng. Việc sửa chỉ giữ lại hình học đầu vào và không bake lại texture.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tiêu thụ bởi tác vụ này. 10 khi tác vụ đã đạt SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

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