Auto Split API

Tách một mô hình 3D thành các phần có thể in riêng biệt — tự động, theo các phần bạn đặt tên, hoặc theo vùng màu — với các đầu nối tùy chọn; các vùng mỏng còn lại sau khi cắt luôn được gia cố để mọi phần đều in đặc chắc.

Auto Split hiện chỉ hỗ trợ các mô hình không có texture. Đối với Ảnh sang 3D và Nhiều ảnh sang 3D, hãy tạo đầu vào với should_texture được đặt thành false. Đầu vào có texture sẽ bị từ chối với mã 400. Hỗ trợ cho mô hình có texture đang được phát triển.

POST/openapi/v1/print/split

Create an Auto Split Task

Endpoint này tạo một tác vụ Auto Split mới. Tác vụ này cắt model của một tác vụ trước đó thành các phần có thể in riêng biệt và trả về model đã được phân đoạn, với mỗi phần là một đối tượng riêng trong file.

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ đã thành công có model cần phân tách. Các loại tác vụ được hỗ trợ: Ảnh sang 3D, Nhiều ảnh sang 3D, Văn bản sang 3D (preview), Remesh, Chuyển đổi, và Đổi kích thước. Tác vụ phải có trạng thái SUCCEEDED, và model của nó phải được tạo bằng Meshy 6 hoặc Meshy 7 (ai_model là meshy-6, meshy-7, hoặc latest). Các model low-poly và Smart Topology (meshy-t2) không được hỗ trợ.

Name
mode
Type
string
mặc định auto
Description
Cách model được chia thành các phần.
Các giá trị khả dụng:
- auto: Meshy tự chọn các đường cắt. prompt bị bỏ qua.
- by_parts: Cắt theo các phần cấu trúc bạn đặt tên trong prompt, chẳng hạn như đầu, tay, và thân.
- by_color: Cắt theo các vùng màu bạn đặt tên trong prompt. Yêu cầu đầu vào được tạo từ một ảnh đã tải lên (Ảnh sang 3D hoặc Nhiều ảnh sang 3D); các đầu vào khác sẽ bị từ chối với mã 400.

Chỉ áp dụng khi mode = by_parts or by_color

Name
prompt
Type
string
Bắt buộc
Description
Mô tả các phần cần phân tách, bằng bất kỳ ngôn ngữ nào. Meshy đọc từ 1 đến 10 tên phần từ đó, vì vậy hãy đặt tên các mảnh thay vì mô tả model — ví dụ split into the figure and the base, hoặc head, torso, left arm, right arm, legs. Tối đa 600 ký tự. Có hai chế độ thất bại: một mô tả đọc như một sự phân tách nhưng chỉ đặt tên ít hơn hai phần (ví dụ split into individual parts) sẽ bị từ chối với mã 400 và không bị tính phí; một mô tả mà Meshy hoàn toàn không thể đọc được sẽ chuyển về auto, tác vụ vẫn chạy và bị tính phí, và phản hồi của nó mang prompt_ignored: true.

Name
target_formats
Type
array
mặc định ["glb"]
Description
Các định dạng để xuất model đã phân tách. Mỗi phần là một đối tượng riêng biệt trong mỗi định dạng. glb luôn được tạo ra và trả về trong model_urls; hãy liệt kê thêm bất kỳ định dạng nào khác bạn muốn.
Các giá trị khả dụng: glb, obj, fbx, usdz, blend, 3mf.
3mf được viết dành cho phần mềm cắt lớp: mỗi phần một đối tượng, mỗi phần trên khe sợi in riêng của nó, để Bambu Studio mở file dưới dạng các phần được tô màu riêng biệt, có thể chọn riêng lẻ (file lưu trữ mang theo cấu hình dự án Bambu Studio; các phần mềm cắt lớp khác đọc hình học). Giống như các định dạng in khác của Meshy, đơn vị là milimet và, vì endpoint này không nhận kích thước mục tiêu, toàn bộ model được co giãn sao cho cạnh dài nhất là 150 mm — cùng giới hạn mà các định dạng xuất in khác sử dụng, được chọn để vừa với mọi bàn in phổ biến. Với layout: "on_plate", giới hạn áp dụng cho toàn bộ bàn đã được bố trí, vì vậy file sẵn sàng để cắt lớp; với assembled, các phần nằm ở vị trí như trong model gốc và bạn tự sắp xếp chúng trong phần mềm cắt lớp.
stl không được hỗ trợ vì định dạng này không thể chứa các phần riêng biệt.
Name
layout
Type
string
mặc định assembled
Description
Cách các phần được sắp xếp trong mỗi định dạng đầu ra, và trong ảnh thu nhỏ.
Các giá trị khả dụng:
- assembled: Các phần giữ nguyên vị trí như trong model gốc.
- on_plate: Các phần được đặt phẳng và dàn trải trên bàn in, sẵn sàng để cắt lớp — cùng cách bố trí như chế độ xem On Plate của ứng dụng web.
Trong cả hai cách bố trí, các file xuất ra chỉ chứa một đối tượng cho mỗi phần và không gì khác: một mảnh mỏng dẹt hoặc mảnh giống như điểm còn sót lại từ một đường cắt sẽ bị loại bỏ trước khi xuất, vì vậy mọi đối tượng bạn thấy trong file đều có thể in được.
Name
connectors
Type
boolean
mặc định false
Description
Thêm các khớp nối mộng-lỗ mộng tại mỗi đường cắt để các phần in vừa khít với nhau.

Chỉ áp dụng khi connectors = true

Name
connector_type
Type
string
mặc định cube
Description
Hình dạng của khớp nối tại mỗi bề mặt cắt.
Các giá trị khả dụng: cube, cylinder.
Name
connector_size
Type
number
mặc định 0.5
Description
Kích thước khớp nối tương đối so với bề mặt cắt.
Phạm vi hợp lệ: 0.1 đến 0.8.
Name
connector_height
Type
number
mặc định 0.1
Description
Khớp nối vươn ra bao xa từ bề mặt cắt, tương đối so với bề mặt cắt.
Phạm vi hợp lệ: 0.1 đến 0.8.

Kết quả trả về

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

Các chế độ thất bạ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 prompt: prompt là bắt buộc khi mode là by_parts hoặc by_color.
- Prompt đặt tên ít hơn hai phần: by_parts / by_color cần ít nhất hai mảnh được đặt tên (ví dụ head, torso, base); một chỉ dẫn chung chung như split into individual parts sẽ bị từ chối. Không có gì bị tính phí.
- Tác vụ đầu vào không được hỗ trợ: input_task_id phải tham chiếu đến một tác vụ đã thành công thuộc loại được hỗ trợ, được tạo bằng Meshy 6 hoặc Meshy 7.
- Đầu vào có texture: Model đầu vào có texture. Hiện tại chỉ hỗ trợ các model không có texture.
- Không có ảnh tham chiếu: by_color yêu cầu đầu vào được tạo từ một ảnh đã tải lên.
- Định dạng không được hỗ trợ: target_formats chứa stl.
- Khớp nối ngoài phạm vi: connector_size hoặc connector_height nằm ngoài khoảng 0.1 đến 0.8.
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
404 - Not Found
Description
input_task_id không tồn tại hoặc không thuộc về tài khoản của bạn.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Các yêu cầu by_parts và by_color cũng chia sẻ giới hạn phân tích prompt là 12 yêu cầu mỗi phút cho mỗi tài khoản.
Name
503 - Service Unavailable
Description
Phân tách dựa trên prompt (by_parts và by_color) tạm thời không khả dụng. Vui lòng thử lại sau, hoặc sử dụng mode: "auto", không bị ảnh hưởng. Không có gì bị tính phí.

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

GET/openapi/v1/print/split/:id

Truy xuất một tác vụ Auto Split

Endpoint này truy xuất một tác vụ Auto Split theo ID của nó.

Tham số

Name
id
Type
path
Description
ID của tác vụ Auto Split cần truy xuất.

Giá trị trả về

Đối tượng Auto Split Task.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

DELETE/openapi/v1/print/split/:id

Xóa một tác vụ Auto Split

Endpoint này sẽ xóa vĩnh viễn một tác vụ Auto Split, 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.

Path Parameters

Name
id
Type
path
Description
ID của tác vụ Auto Split cần xóa.

Kết quả trả về

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

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/split

List Auto Split Tasks

Endpoint này cho phép bạn lấy danh sách các tác vụ Auto Split.

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ục trên mỗi trang. Mặc định là 10 mục. Giá trị tối đa cho phép là 100 mục; các giá trị lớn hơn sẽ được giới hạn về 100.
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.

Giá trị trả về

Trả về danh sách phân trang gồm các Đối tượng Tác vụ Auto Split.

Request

GET

/openapi/v1/print/split

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/split/:id/stream

Truyền trực tiếp một Tác vụ Auto Split

endpoint này truyền trực tiếp (stream) các cập nhật theo thời gian thực cho một tác vụ Auto Split bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Auto Split cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng Đối tượng Tác vụ Auto Split dưới dạng Server-Sent Events.

Mỗi sự kiện message mang theo toàn bộ đối tượng tác vụ như được trả về bởi Truy xuất một Tác vụ Auto Split, bao gồm consumed_credits, các mốc thời gian và prompt_ignored; trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường thay đổi giữa các khung dữ liệu là progress, status, started_at và preceding_tasks, còn model_urls, thumbnail_url, part_count và parts sẽ xuất hiện khi tác vụ đạt trạng thái SUCCEEDED. Một sự kiện error chỉ mang theo status_code và message, vì vậy hãy phân nhánh dựa trên tên sự kiện trước khi đọc status.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

The Auto Split Task Object

Một tác vụ Auto Split chỉ mang các thuộc tính bên dưới. Các trường generation-prompt mà các đối tượng tác vụ khác có (name, object_prompt, texture_prompt, v.v.), model_url đơn lẻ, và texture_urls không bao giờ được điền cho một lần split và không được trả về. Các thuộc tính được điền khi tác vụ chạy (thumbnail_url, model_urls, các dấu thời gian) luôn hiện diện, để trống cho đến khi có giá trị, vì vậy tập hợp các khóa không thay đổi giữa PENDING và SUCCEEDED.

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) làm chi tiết triển khai cho id tác vụ, 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ụ. Giá trị là print-split.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống của mô hình đã split, mỗi định dạng một URL. Mỗi phần là một đối tượng riêng biệt trong tệp. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được yêu cầu.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng GLB.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng OBJ.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng FBX.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng USDZ.
- Name
  blend
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng Blender.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng 3MF: mỗi phần là một đối tượng riêng, mỗi đối tượng nằm trên khe sợi in (filament slot) riêng, tính bằng milimét, được co giãn sao cho cạnh dài nhất là 150 mm, kèm theo cấu hình dự án Bambu Studio.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống của bản xem trước được kết xuất của mô hình đã split, với mỗi phần có một màu riêng biệt, theo layout đã yêu cầu.
Name
prompt_ignored
Type
boolean
Description
true khi prompt của một yêu cầu by_parts hoặc by_color không nêu tên phần nào, nên Meshy đã tự động split mô hình thay vào đó — tên các phần trong kết quả là do Meshy đặt, không phải của bạn. Có mặt kể từ PENDING. Bị bỏ qua đối với các tác vụ auto và bất cứ khi nào prompt được tuân theo.
Name
part_count
Type
integer
Description
Số lượng phần có thể in được trong mô hình đã split — mỗi đối tượng trong các tệp xuất ra là một phần. Các mảnh vụn bị suy sụp mà quá trình phân đoạn không thể biến thành một mảnh có thể in được sẽ bị loại bỏ khỏi các tệp trước khi xuất và không được tính.
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ụ đã thành công, 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, CANCELED.
Name
preceding_tasks
Type
integer
Description
Số lượng các 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 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 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 tham chiếu đầy đủ về đố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. Luôn hiện diện: 10 khi tác vụ đã được chấp nhận, và 0 đối với các tác vụ FAILED vì khoản phí sẽ được hoàn lại khi thất bại. Xóa một tác vụ trong khi nó vẫn đang PENDING cũng sẽ hoàn lại phí.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}