API In Nhiều Màu

Chuyển đổi các mô hình 3D sang định dạng 3MF in 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 một tác vụ in 3D đa màu sắc

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

Tham số

Chỉ cần một trong hai 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ụ đã 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 là SUCCEEDED.

Name
model_url
Type
string
Bắt buộc
Description
URL 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ố 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
Phong cách màu sắc trực quan của tệp 3MF được tạo ra.
Các giá trị có sẵn:
- realistic: Lấy mẫu màu trực tiếp từ texture của mô hình để có chi tiết ảnh chân thực. Tạo ra một tệp lớn hơn.
- cartoon: Làm phẳng màu sắc thành các vùng sạch, đồng nhất cho một cái nhìn phong cách. Tạo ra một tệp nhỏ hơn.

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.

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ố: 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: model_url không thể tải xuống.
- 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.
- Phong cách không hợp lệ: Giá trị phải là realistic hoặc cartoon.
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.

Yêu cầu

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

Phản hồi

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

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

Truy xuất Nhiệm Vụ In 3D Đa Màu

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

Tham số

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

Trả về

Đối tượng Nhiệm Vụ In 3D.

Yêu cầu

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

Phản hồi

{
  "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 một Nhiệm Vụ In 3D Nhiều Màu

Endpoint này xóa vĩnh viễn một nhiệm vụ in 3D nhiều 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ể đảo ngược.

Tham Số Đường Dẫn

Name
id
Type
path
Description
ID của nhiệm vụ in 3D nhiều 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

Danh sách Nhiệm vụ In 3D Đa Màu

Endpoint này cho phép bạn truy xuất danh sách các nhiệm 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 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 Các Đối tượng Nhiệm vụ In 3D.

Yêu cầu

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

Phản hồi

[
  {
    "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 tải một Nhiệm vụ In 3D Nhiều Màu

Endpoint này truyền tải các cập nhật theo thời gian thực cho một nhiệm vụ in 3D nhiều màu sử dụng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho nhiệm vụ in 3D nhiều màu để truyền tải.

Trả về

Trả về một luồng của Các Đối tượng Nhiệm vụ In 3D dưới dạng Server-Sent Events.

Đối với các nhiệm 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.

Yêu cầu

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

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-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 Nhiệm Vụ In 3D

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ụ In 3D. Giá trị là print-multi-color.
Name
model_urls
Type
object
Description
URL có thể tải xuống cho 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 thay vì trả về một chuỗi rỗng.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống cho tệp 3MF đa màu.
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, điều này sẽ trở thành 100.
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.
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ụ được 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ụ được 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
task_error
Type
object
Description
Chi tiết lỗi cho các nhiệm vụ thất bại. Xem Lỗi để tham khảo đầy đủ đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng tiêu thụ bởi nhiệm vụ này. Có mặt khi trạng thái nhiệm vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các nhiệm 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
}