Multi-Color Print API

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

POST/openapi/v1/print/multi-color

Create a Multi-Color 3D Print Task

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

Tác vụ chạy ở chế độ nền. Để biết thời gian xử lý thường mất bao lâu, xem Thời Gian Xử Lý.

Tham số

Chỉ một trong hai tham số input_task_id hoặc model_url là bắt buộc. 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 tác vụ đã thành công để sử 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 của một mô hình .glb hoặc .fbx, hoặc một URL data: dạng base64 của GLB (data:model/gltf-binary;base64,...). Tệp .fbx phải được gửi dưới dạng URL http hoặc https.
Kích thước tệp tối đa: 400 MB đối với URL http hoặc https, 100 MB đối với URI data:.
Một tệp trên 100 MB có thể có tối đa 8.000.000 mặt (faces). Các mặt được tính dưới dạng tam giác: một hình tứ giác (quad) được tính là 2, và một lưới được vẽ nhiều lần được tính một lần cho mỗi bản sao. Trên 100 MB, tệp FBX phải là FBX nhị phân 7.1 trở lên, và tệp GLB không được sử dụng nén Draco.

Name
max_colors
Type
integer
mặc định 4
Description
Số lượng màu tối đa trong bảng màu đầu ra.
Phạm vi hợp lệ: 1 đến 16.
Name
style
Type
string
mặc định realistic
Description
Kiểu màu sắc trực quan của tệp 3MF được tạo ra.
Các giá trị khả dụng:
- realistic: Lấy mẫu màu trực tiếp từ texture của mô hình để tạo chi tiết tinh tế, chân thực như ảnh chụp. Tạo ra tệp lớn hơn.
- cartoon: Làm phẳng màu sắc thành các vùng đồng nhất, gọn gàng để tạo phong cách cách điệu. Tạo ra tệp nhỏ hơn.
Đầu vào phải mang thông tin màu sắc: realistic yêu cầu một texture màu cơ bản duy nhất với tọa độ UV trên mọi phần của lưới; cartoon cũng chấp nhận màu theo đỉnh (per-vertex). Các mô hình không có texture (màu trắng) sẽ bị từ chối — xem model_missing_texture.
Name
max_depth
Type
integer
mặc định 4
Description
Độ sâu phân chia được sử dụng để lấy mẫu màu texture lên lưới. Giá trị cao hơn sẽ nắm bắt chi tiết màu sắc tinh tế hơn nhưng tạo ra tệp lớn hơn. Chỉ áp dụng cho kiểu realistic; bị bỏ qua đối với cartoon.
Phạm vi hợp lệ: 3 đến 6.
Name
printer_brand
Type
string
mặc định bambu
Description
Thương hiệu máy in mà bản thiết lập phần mềm cắt lớp (slicer preset) của hãng đó sẽ được ghi vào tệp 3MF, để tệp mở trong phần mềm cắt lớp của thương hiệu đó với máy in, vật liệu in và hồ sơ quy trình tương ứng. Mỗi thương hiệu sử dụng máy in mặc định với đầu phun 0,4 mm.
Các giá trị khả dụng: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Giá trị trả về

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

Chế Độ Lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- 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ệp mô hình quá lớn: Tệp model_url vượt quá 400 MB (URL http hoặc https) hoặc 100 MB (URI data:).
- Quá nhiều mặt (faces): Tệp model_url vượt quá 100 MB và có nhiều hơn 8.000.000 mặt. Hãy giảm số lượng mặt, sau đó gửi lại tệp.
- ASCII FBX vượt quá 100 MB: Tệp model_url là ASCII FBX vượt quá 100 MB. Hãy gửi dưới dạng FBX nhị phân hoặc GLB.
- Tệp mô hình không thể đọc được: Tệp model_url vượt quá 100 MB và không thể đọc được phần header của nó, ví dụ như một GLB được nén Draco, hoặc một FBX nhị phân cũ hơn 7.1.
- Header mô hình quá phức tạp: Tệp model_url vượt quá 100 MB và phần header của nó có quá nhiều lưới, node hoặc bản ghi để kiểm tra. Hãy giảm số lượng đối tượng trong tệp, sau đó gửi lại.
- 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.
- style không hợp lệ: Giá trị phải là realistic hoặc cartoon.
- max_depth không hợp lệ: Giá trị phải nằm trong khoảng từ 3 đến 6.
- printer_brand không hợp lệ: Giá trị phải là một trong các thương hiệu được liệt kê ở trên.
- Không có nguồn màu: Mô hình đầu vào không có texture màu cơ bản (realistic cần một texture duy nhất, với UV, trên mọi phần của lưới) và không có màu theo đỉnh (cartoon chấp nhận cả hai). Hãy tạo texture cho mô hình trước, hoặc sử dụng cartoon cho các mô hình có màu theo đỉnh. Các tệp .fbx được tải lên sẽ được kiểm tra sau khi tác vụ chuẩn hóa chúng và sẽ thất bại với model_missing_texture thay vì lỗi trên.
Name
401 - Unauthorized
Description
Xác thực không thành công. 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 a multi-color 3MF with a Creality slicer preset
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,
    "printer_brand": "creality"
  }'

Response

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

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

Xóa một 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ạng thái Tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ bị xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đang ở 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 tác vụ đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, rồi mới xóa nó.

Một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED hoặc CANCELED) sẽ bị xóa mà không được hoàn tín dụng.

Giá trị 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/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

// 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/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 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 kích thước 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 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.

Giá trị trả về

Trả về danh sách phân trang gồm 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

Stream a Multi-Color 3D Print 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ụ in 3D đa màu bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ in 3D đa màu cần truyền trực tiếp.

Giá trị 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ụ ở trạng thái 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
Đị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 (k-sortable UUID) cho id tác vụ như là 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ụ In 3D. Giá trị là print-multi-color.
Name
model_urls
Type
object
Description
URL có thể tải xuống của tệp mô hình 3D được tạo bởi Meshy. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được tạo ra, thay vì trả về một chuỗi rỗng.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống của tệp 3MF đa màu.
Name
progress
Type
integer
Description
progress của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã hoàn thành, giá trị 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 các giá trị 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 khi 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 thành, tính bằng mili giây. Nếu tác vụ chưa hoàn thành, 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 đầy đủ tham chiếu đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi tác vụ này. Xuất hiện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các tác vụ FAILED (tín dụng sẽ đượ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
}

Multi-Color Print API

Create a Multi-Color 3D Print Task

Tham số

Giá trị trả về

Chế Độ Lỗi

Request

Response

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

Tham số

Giá trị trả về

Request

Response

Xóa một Tác vụ In 3D Đa Màu

Tham số Đường dẫn

Trạng thái Tác vụ

Giá trị Trả về

Request

Response

Liệt Kê Tác Vụ In 3D Đa Màu

Tham số

Thuộc tính tùy chọn

Giá trị trả về

Request

Response

Stream a Multi-Color 3D Print Task

Tham số

Giá trị trả về

Request

Response Stream

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

The 3D Print Task Object