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ỗ hổng, cạnh non-manifold và mặt suy biến.

POST/openapi/v1/print/analyze

Tạo một Analyze Printability Task

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

Nếu task đầu vào đã có sẵn dữ liệu khả năng in được lưu trong bộ nhớ đệm, task được trả về sẽ sẵn sàng ngay lập tức và lệnh GET đầu tiên trên task đó 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 cung cấp một trong hai giá trị input_task_id hoặc model_url. Nếu cả hai đều đượ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 task đã thành công mà bạn sở hữu. Các loại task được hỗ trợ: Ảnh sang 3D, Nhiều ảnh sang 3D, Văn bản sang 3D, Remesh, và Tạo lại texture. Task phải sử dụng Meshy 6 trở lên (bao gồm cả Meshy 7) 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 http, https, hoặc một URL data: (URL data sẽ bỏ qua việc kiểm tra phần mở rộng tệp).

Giá trị trả về

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

Các chế độ lỗ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 một 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 của model_url vượt quá 100 MB.
- Task chưa thành công: task đượ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
Task 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
Các nguyên nhân phổ biến:
- Task không tồn tại hoặc đã bị xóa.
- Task sử dụng một model 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 gốc không còn tồn tại trong bộ lưu trữ.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá hạn ngạch task đang chờ xử lý hoặc giới hạn tốc độ của mình.

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

Retrieve an Analyze Printability Task

Endpoint này truy xuất một tác vụ Phân tích khả năng in theo 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.

Kết quả trả về

Đối tượng Tác vụ Phân tích khả năng in. Trường printability sẽ 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 cùng 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ạng thái tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ được xóa và số tín dụng đã bị trừ 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 không thể bị 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 việc 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 tín dụng.

Kết quả 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/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

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

List Analyze Printability Tasks

Endpoint này cho phép bạn lấy 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 dùng 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ề danh sách phân trang các Đố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

Stream an Analyze Printability Task

Endpoint này truyền trực tiếp 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 Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ phân tích khả năng in cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng Đối tượng Tác vụ Phân tích khả năng in dưới dạng Server-Sent Events.

Mỗi khung dữ liệu mang theo toàn bộ đối tượng tác vụ cho giai đoạn đó — 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 là null. 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.
// 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-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 Task Phân tích khả năng in

Name
id
Type
string
Description
Định danh duy nhất cho task. Mặc dù chúng tôi sử dụng UUID có thể k-sắp xếp làm chi tiết triển khai cho id của task, 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 task phân tích khả năng in. Giá trị là print-analyze.
Name
status
Type
string
Description
Trạng thái của task. Các giá trị có thể là một trong số PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress của task. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0. Khi task đã thành công, giá trị này sẽ trở thành 100.
Name
preceding_tasks
Type
integer
Description
Số lượng các task đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái của task là PENDING.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi task được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi task được bắt đầu, tính bằng mili giây. Nếu task 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 task hoàn tất, tính bằng mili giây. Nếu task 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ả của task sẽ hết hạn khỏi hệ thống, tính bằng mili giây. 0 nếu task chưa hoàn tất.
Name
task_error
Type
object
Description
Thông tin lỗi nếu task thất bại. Thuộc tính này là null nếu task 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 task đạt trạng thái 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 số:
  
  healthy: không có lỗi và không có cảnh báo.
  
  warning: có ít nhất một cảnh báo, không có lỗi.
  
  error: có í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 đưa ra khi mô hình không kín nước (watertight), 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ỗ hổng.
- 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à được đóng kín).
  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ỗ hổng (vòng lặp 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
}