API In nhiều màu

Chuyển đổi mô hình 3D sang định dạng 3MF nhiều màu cho in 3D, với bảng màu có thể cấu hình lên đến 16 màu.

POST/openapi/v1/print/multi-color

Tạo tác vụ in 3D đa màu

endpoint này tạo một tác vụ in 3D đa màu mới. Tác vụ chuyển đổi một mô hình 3D thành tệp 3MF đa màu phù hợp để in 3D.

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 để dùng làm đầu vào. 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.

Name
model_url
Type
string
Bắt buộc
Description
URL có thể truy cập công khai hoặc Data URI của một mô hình 3D. Hiện tại chúng tôi hỗ trợ các định dạng .glb và .fbx.

Name
max_colors
Type
integer
mặc định 4
Description
Số màu tối đa trong bảng màu đầu ra.
Phạm vi hợp lệ: 1 đến 16.
Name
max_depth
Type
integer
mặc định 4
Description
Độ sâu quadtree cho độ chính xác màu. Giá trị cao hơn tạo ra ranh giới màu mịn hơn nhưng làm tăng kích thước tệp.
Phạm vi hợp lệ: 3 đến 6.

Trả về

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

Chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Nguyên nhân thường gặp:
- Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
- Định dạng mô hình không hợp lệ: model_url trỏ đến một tệp có phần mở rộng không được hỗ trợ (chỉ hỗ trợ .glb và .fbx).
- URL không thể truy cập: Không thể tải xuống model_url.
- Tác vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một tác vụ thành công.
- max_colors không hợp lệ: Giá trị phải nằm trong khoảng từ 1 đến 16.
- max_depth không hợp lệ: Giá trị phải nằm trong khoảng từ 3 đến 6.
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
Không đủ tín dụng để thực hiện tác vụ này.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "max_depth": 5
  }'

Response

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

GET/openapi/v1/print/multi-color/:id

Truy xuất một tác vụ in 3D đa màu

endpoint này truy xuất một tác vụ in 3D đa màu theo ID của nó.

Tham số

Name
id
Type
path
Description
ID của tác vụ in 3D cần truy xuất.

Trả về

Đối tượng Tác vụ In 3D.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

Xóa tác vụ in 3D đa màu

Endpoint này xóa vĩnh viễn một tác vụ in 3D đa màu, bao gồm tất cả các mô hình và dữ liệu liên quan. 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ụ in 3D đa màu cần xóa.

Trả về

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

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Liệt kê Tác vụ In 3D Đa màu

endpoint này cho phép bạn truy xuất danh sách các tác vụ in 3D đa màu.

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 được phép là 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp theo. Các giá trị khả dụng:
- +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 Các Đối tượng Tác vụ In 3D.

Request

GET

/openapi/v1/print/multi-color

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

Truyền phát tác vụ in 3D đa màu

endpoint này truyền phát các cập nhật theo thời gian thực cho một tác vụ in 3D đa màu bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ in 3D đa màu cần truyền phát.

Trả về

Trả về một luồng Đối tượng tác vụ in 3D 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.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Đối tượng tác vụ in 3D

Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ. Mặc dù chúng tôi 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 tác vụ In 3D. Giá trị là print-multi-color.
Name
model_urls
Type
object
Description
URL có thể tải xuống đến tệp mô hình 3D do Meshy tạo. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được tạo, thay vì trả về một chuỗi rỗng.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống đến tệp 3MF nhiều màu.
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, thuộc tính này sẽ trở thành 100.
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.
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 của thời điểm tác vụ được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian của thời điểm 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 của thời điểm 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
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tác vụ này tiêu thụ. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}