API Phân tích khả năng in

Phân tích một mô hình 3D về khả năng in FDM — độ kín nước, thể tích, lỗ, cạnh non-manifold và mặt suy biến.

POST/openapi/v1/print/analyze

Tạo tác vụ Phân tích khả năng in

Endpoint này tạo một tác vụ phân tích khả năng in mới. Tác vụ đánh giá một mô hình 3D và báo cáo các chỉ số khả năng in của nó.

Nếu tác vụ đầu vào đã có khả năng in được lưu trong bộ nhớ đệm, tác vụ được trả về sẽ sẵn sàng ngay lập tức và lần GET đầu tiên trên tác vụ đó sẽ trả về kết quả phân tích mà không cần đi qua worker.

Tham số

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

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 sử dụng Meshy 6 (hoặc bất kỳ mô hình Preview nào) và phải có trạng thái SUCCEEDED.

Name
model_url
Type
string
Bắt buộc
Description
URL của một mô hình 3D cần phân tích. 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: (data URL bỏ qua kiểm tra phần mở rộng).

Giá trị trả về

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

Các chế độ 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ố: không cung cấp cả input_task_id lẫn model_url.
- 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: phần body của 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 progress, hoặc đã thất bại.
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
403 - Forbidden
Description
Tác vụ tồn tại nhưng thuộc sở hữu của một người dùng khác.
Name
404 - Not Found
Description
Nguyên nhân phổ biến:
- Tác vụ không tồn tại hoặc đã bị xóa.
- Tác vụ sử dụng một mô hình cũ hơn Meshy 6, hoặc mode của nó không tạo ra một asset 3D.
- Tệp mô hình bên dưới không còn khả dụng trong bộ lưu trữ.
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/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/analyze/:id

Truy xuất một tác vụ Phân tích khả năng in

endpoint này truy xuất một tác vụ Phân tích khả năng in theo ID của tác vụ đó.

Tham số

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

Trả về

Đối tượng tác vụ Phân tích khả năng in. Trường printability là null cho đến khi tác vụ đạt SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Xóa tác vụ Phân tích khả năng in

endpoint này xóa vĩnh viễn một tác vụ phân tích khả năng in và kết quả được lưu trong bộ nhớ đệm 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ụ phân tích khả năng in cần xóa.

Trả về

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

Request

DELETE

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

Liệt kê tác vụ Phân tích khả năng in

endpoint này cho phép bạn truy xuất danh sách các tác vụ phân tích 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 dù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 được phân trang của Đối tượng tác vụ Phân tích khả năng in.

Request

GET

/openapi/v1/print/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

Truyền phát một tác vụ Phân tích khả năng in

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

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ analyze-printability cần truyền phát.

Trả về

Trả về một luồng các Đối tượng tác vụ Phân tích 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 printability chỉ được gửi khi tác vụ đạt trạng thái SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

Đối tượng tác vụ Phân tích 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 theo 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 của tác vụ analyze-printability. Giá trị là print-analyze.
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
printability
Type
object
Description
Kết quả đánh giá khả năng in. null cho đến khi tác vụ đạt SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Phiên bản schema của kết quả khả năng in. Hiện tại là v1.
- Name
  status
  Type
  string
  Description
  Trạng thái tổng thể. Một trong:
  
  healthy: không có lỗi và không có cảnh báo.
  
  warning: ít nhất một cảnh báo, không có lỗi.
  
  error: ít nhất một lỗi.
  
  unknown: không thể phân tích mô hình.
- Name
  issue_count
  Type
  integer
  Description
  Tổng số vấn đề, bằng error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Số lượng vấn đề cấp lỗi. Lỗi được tạo ra khi mô hình không kín nước, có thể tích không dương, hoặc có cạnh non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Số lượng vấn đề cấp cảnh báo. Cảnh báo được tạo ra khi mô hình chứa mặt suy biến hoặc lỗ.
- Name
  metrics
  Type
  object
  Description
  Các chỉ số hình học thô do bộ đánh giá trả về.
  Name
  is_watertight
  Type
  boolean
  Description
  true khi lưới không có cạnh biên (tức là đã đóng).
  Name
  volume
  Type
  number
  Description
  Thể tích của mô hình tính bằng mét khối.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Số lượng cạnh non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Số lượng mặt suy biến (mặt có diện tích bằng không hoặc không hợp lệ).
  Name
  holes
  Type
  integer
  Description
  Số lượng lỗ (vòng biên) trong lưới.
- Name
  evaluated_at
  Type
  timestamp
  Description
  dấu thời gian khi quá trình phân tích được tính toán, tính bằng mili giây kể từ epoch.
Name
consumed_credits
Type
integer
Description
Luôn là 0. endpoint này miễn phí.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}