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

Phân tích một mô hình 3D cho 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 một 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ớ cache, tác vụ trả về sẽ sẵn sàng ngay lập tức và lần GET đầu tiên trên nó sẽ trả về kết quả phân tích mà không cần thông qua worker.

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.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ đã hoàn thành 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 mới hơn (bao gồm Meshy 7) và phải có trạng thái là SUCCEEDED.

Name
model_url
Type
string
Bắt buộc
Description
URL của một mô hình 3D để 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 http, https, hoặc một URL data: (các URL dữ liệu bỏ qua kiểm tra phần mở rộng).

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ế độ 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 hoàn thành: tác vụ được tham chiếu vẫn đang chờ xử lý, đang tiến hành, 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 người dùng khác.
Name
404 - Not Found
Description
Các 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 chế độ của nó không tạo ra một asset 3D.
- Tệp mô hình cơ bản không còn khả dụng trong lưu trữ.
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 độ.

Yêu cầu

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

Phản hồi

{
  "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 bằng ID của nó.

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 khả năng in là null cho đến khi tác vụ đạt trạng thái 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 một 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ả đã 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

Danh sách các 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 để 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ụ 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

Phát trực tuyến một tác vụ Phân tích khả năng in

Endpoint này phát trực tuyến các cập nhật theo thời gian thực cho một tác vụ phân tích khả năng in bằng cách sử dụng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ phân tích khả năng in để phát trực tuyến.

Trả về

Trả về một luồng của Đố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 cần thiết progress và status. Khối printability chỉ được gửi khi tác vụ đạt SUCCEEDED.

Yêu cầu

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

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-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 Nhiệm vụ Phân tích 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 k cho 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ụ phân tích khả năng in. Giá trị là print-analyze.
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.
Name
printability
Type
object
Description
Kết quả đánh giá khả năng in. null cho đến khi nhiệm vụ đạt SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Phiên bản lược đồ 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 các giá trị:
  
  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: mô hình không thể phân tích.
- 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 đưa 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 đưa 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ô được trả về bởi bộ đánh giá.
  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 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
}