API Sửa khả năng in

Sửa một 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 cho việc 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ụ sẽ chạy quá trình sửa topology trên mô hình 3D và trả về phiên bản kín nước (watertight), 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 file .stl qua model_url, model_urls.stl trong phản hồi sẽ chứa lưới đã được sửa và các trường định dạng khác sẽ để trống. Đường dẫn input_task_id luôn đọc file GLB của tác vụ nguồn, do đó đầu ra sẽ là .glb.

Tham số

Chỉ bắt buộc một trong hai trường input_task_id hoặc model_url. 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ị loại bỏ trong quá trình sửa do có thay đổi về 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 đã được 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, .gltf, .obj, .fbx, .stl. Kích thước file tối đa: 100 MB. Phải sử dụng http, https, hoặc URL data: (URL data sẽ bỏ qua việc kiểm tra phần mở rộng).

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

Kết quả 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 vừa được tạo.

Các trường hợp thất bại

Name
400 - Bad Request
Description
Yêu cầu không hợp lệ. Các nguyên nhân phổ biến:
- Thiếu tham số: không có input_task_id hoặc model_url nào được cung cấp.
- UUID không hợp lệ: input_task_id không phải là một UUID hợp lệ.
- URL mô hình không hợp lệ: model_url sai định dạng, sử dụng scheme không được hỗ trợ, hoặc có phần mở rộng file không được hỗ trợ.
- File 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ờ xử lý, đang thực hiện, hoặc đã thất bại.
- Thiếu GLB: tác vụ được tham chiếu không có asset GLB nào để 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
Các 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 ngạch tác vụ đang chờ xử lý 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.

Giá trị 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 trạng thái SUCCEEDED. Chỉ trường model_urls khớp với định dạng đầu vào mới được điền giá trị.

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

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 cùng với đầu ra đã được sửa của nó. Hành động này không thể hoàn tá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ạng thái tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ bị xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đã ở trạng thái IN_PROGRESS thì không thể xóa: yêu cầu sẽ bị từ chối với mã 409 Conflict và tác vụ vẫn tiếp tục chạy. Tín dụng cho một tác vụ mà worker đã bắt đầu xử lý sẽ không được hoàn lại, vì vậy xóa nó giữa chừng sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi nó đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, rồi mới xóa.

Một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED hoặc CANCELED) sẽ được xóa mà không được hoàn tiền.

Giá trị trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

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

Danh sách các tác vụ Sửa khả năng in

Endpoint này cho phép bạn lấy về 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 số lượng mỗi trang. Mặc định là 10 mục. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
Description
Trường dùng để sắp xếp. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo tăng dần.
- -created_at: Sắp xếp theo thời gian tạo giảm dần.

Kết quả trả về

Trả về một danh sách phân trang gồm các Đố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=***",
      "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

Truyền trực tuyến một tác vụ Sửa khả năng in

Endpoint này truyền trực tuyến 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 trực tuyến.

Giá trị trả về

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

Mỗi khung dữ liệu mang toàn bộ đối tượng tác vụ cho giai đoạn hiện tại — cùng cấu trúc mà endpoint Get trả về — vì vậy khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra đơn giản là chưa được điền (null, [] hoặc {}) và finished_at sẽ là null. 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.
// 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
}

The Repair Printability Task Object

Name
id
Type
string
Description
Định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng k-sortable UUID cho id của 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 của tác vụ repair-printability. 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 các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress của tác vụ. Nếu tác vụ chưa 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 các tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi 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ụ bắt đầu, tính bằng mili giây. Nếu tác vụ chưa 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 thành, tính bằng mili giây. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả của 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 thành.
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ụ không 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.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho mô hình 3D đã được sửa. Chỉ trường tương ứng với định dạng đầu vào được điền dữ liệu; 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 cho GLB đã được sửa. Được điền khi đầu vào là GLB hoặc khi input_task_id được sử dụng.
- Name
  gltf
  Type
  string
  Description
  URL có thể tải xuống cho GLTF đã được sửa. Được điền khi đầu vào là tệp GLTF được tải lên.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống cho FBX đã được sửa. Được điền khi đầu vào là tệp FBX được tải lên.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống cho OBJ đã được sửa. Được điền khi đầu vào là tệp OBJ được tải lên.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống cho STL đã được sửa. Được điền khi đầu vào là tệp STL được tải lên.
- 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ụ repair-printability.
- 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ụ repair-printability.
- 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ụ repair-printability.
Name
thumbnail_url
Type
string
Description
URL của hình ảnh xem trước được kết xuất từ mô hình đã được sửa.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống cho 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 kết xuất thành công; nếu không, trường này sẽ được 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 tạo lại texture.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi tác vụ này. 10 khi tác vụ đã đạt trạng thái SUCCEEDED. Trả về 0 đối với 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=***",
    "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
}