API Sửa khả năng in

Sửa một mô hình 3D cho 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 một 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ụ này thực hiện sửa topology trên một 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 của 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 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 đượ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 thay đổi hình học. Để thêm lại texture, sử dụng Retexture API 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à Retexture. 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ột 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 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 được đặt thành true, tác vụ sẽ thêm vào việc render một phiên bản nền trong suốt (RGBA) của bản xem trước và trả về nó 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 chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không chấp nhận được. Các nguyên nhân phổ biến:
- Thiếu tham số: không có input_task_id hoặc model_url đượ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 bị sai định dạng, sử dụng một giao thức 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ờ xử lý, đang tiến hành, 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
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 một gói trả phí. Nâng cấp tại trang đăng ký.
- Tín dụng không đủ: giới hạn tín dụng không gian làm việc đã đạt.
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

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

Endpoint này lấy một tác vụ sửa khả năng in bằng 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 lấy.

Trả về

Đối tượng Tác vụ Sửa Khả năng In. Khối model_urls 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 được điền.

Yêu cầu

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

Phản hồi

{
  "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 một 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

Danh sách 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 cho phép là 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp. Các giá trị có sẵn:
- +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 phân trang của Đối tượng Tác vụ Sửa Khả năng In.

Yêu cầu

GET

/openapi/v1/print/repair

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

Phản hồi

[
  {
    "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 tải một tác vụ Sửa khả năng in

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ sửa khả năng in để truyền tải.

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 SUCCEEDED.

Yêu cầu

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

Luồng Phản hồi

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

Đối tượng Nhiệm vụ Sửa Khả năng In

Name
id
Type
string
Description
Định danh duy nhất cho nhiệm vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k cho các id nhiệm 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 nhiệm vụ sửa khả năng in. Giá trị là print-repair.
Name
status
Type
string
Description
Trạng thái của nhiệm vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Tiến độ của nhiệm vụ. Nếu nhiệm vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi nhiệm vụ đã thành công, giá trị này sẽ trở thành 100.
Name
preceding_tasks
Type
integer
Description
Số lượng nhiệm vụ trước đó.
Giá trị của trường này chỉ có ý nghĩa nếu trạng thái nhiệm vụ là PENDING.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi nhiệm vụ được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi nhiệm vụ bắt đầu, tính bằng mili giây. Nếu nhiệm 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 nhiệm vụ hoàn thành, tính bằng mili giây. Nếu nhiệm 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ả nhiệm vụ sẽ hết hạn trong hệ thống, tính bằng mili giây. 0 nếu nhiệm vụ chưa hoàn thành.
Name
task_error
Type
object
Description
Thông tin lỗi nếu nhiệm vụ thất bại. Thuộc tính này là null nếu nhiệm 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 sai.
Name
model_urls
Type
object
Description
URL có thể tải xuống của mô hình 3D đã được 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 trống.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống của 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 của GLTF đã được sửa. Được điền khi đầu vào là tải lên GLTF.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống của FBX đã được sửa. Được điền khi đầu vào là tải lên FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống của OBJ đã được sửa. Được điền khi đầu vào là tải lên OBJ.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống của STL đã được sửa. Được điền khi đầu vào là tải lên STL.
- Name
  usdz
  Type
  string
  Description
  Dành cho đầu ra USDZ. Luôn là chuỗi trống cho các nhiệm vụ sửa khả năng in.
- Name
  3mf
  Type
  string
  Description
  Dành cho đầu ra 3MF. Luôn là chuỗi trống cho các nhiệm vụ sửa khả năng in.
- Name
  mtl
  Type
  string
  Description
  Dành cho đầu ra MTL. Luôn là chuỗi trống cho các nhiệm vụ sửa khả năng in.
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 của phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ có khi nhiệm 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ẽ bị bỏ qua.
Name
texture_urls
Type
array
Description
Luôn là một mảng trống. Sửa chữa chỉ bảo toàn hình học đầu vào và không tái tạo lại các texture.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi nhiệm vụ này. 10 khi nhiệm vụ đã đạt SUCCEEDED. Trả về 0 cho các nhiệm vụ FAILED (tín dụng được hoàn trả 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
}