API Auto Split

Chia 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 in ra đều đặc.

Kết quả chia tách không giữ lại texture đầu vào. Auto Split chấp nhận đầu vào có texture, vì vậy bạn không cần tạo lại mô hình với should_texture: false. Nó xây dựng lại các phần đã cắt và gán cho mỗi phần một màu đỉnh (vertex color) đồng nhất; không có bản đồ texture đầu vào nào được mang vào bất kỳ định dạng xuất nào.

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 mô hình 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ề mô hình đã được phân đoạn, với mỗi phần là một đối tượng riêng trong tệp.

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

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ó mô hình cầ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 (bản xem trước), Remesh, Chuyển đổi, và Đổi kích thước. Tác vụ phải có trạng thái SUCCEEDED, và mô hình của nó phải được tạo bằng Meshy 6 hoặc Meshy 7 (ai_model là meshy-6, meshy-7, meshy-7.1, hoặc latest). Các mô hình low-poly và Smart Topology (meshy-t2, meshy-t2.5) không được hỗ trợ. Mô hình có texture được chấp nhận, nhưng texture của nó sẽ không được mang vào kết quả.

Name
mode
Type
string
mặc định auto
Description
Cách mô hình được chia thành các phần.
Các giá trị khả dụng:
- auto: Meshy tự chọn các vết cắt. prompt bị bỏ qua.
- by_parts: Cắt theo các bộ phận cấu trúc bạn nêu tên trong prompt, chẳng hạn như đầu, cánh tay, và thân.
- by_color: Cắt theo các vùng màu bạn nêu 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. Ranh giới vùng màu được lấy từ ảnh nguồn, không phải từ texture của mô hình đầu vào. Đối với Nhiều ảnh sang 3D, Auto Split sử dụng ảnh nguồn đầu tiên.

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 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 nêu tên các mảnh thay vì mô tả mô hình, ví dụ split into the figure and the base, hoặc head, torso, left arm, right arm, legs. Nêu tên một phần duy nhất cũng được: mọi thứ bạn không nêu tên sẽ trở thành một phần còn lại, vì vậy the head sẽ tách mô hình thành phần đầu và phần còn lại, giống như trong ứng dụng web. Tối đa 600 ký tự. Mô tả yêu cầu không tách gì cả, hoặc nêu tên hơn 10 phần, sẽ bị từ chối với mã 400 và không bị tính phí. Nếu Meshy không thể đọc được tên phần nào từ mô tả, nó sẽ tách theo các phần mà nó xác định được trong ảnh tham chiếu của mô hình thay vào đó, theo mode bạn đã chọn: tác vụ vẫn chạy và bị tính phí, và nó mang prompt_ignored: true. Nếu mô hình không có ảnh tham chiếu, hoặc Meshy tìm thấy ít hơn hai phần trong đó, yêu cầu đó sẽ bị từ chối với mã 400 thay vào đó và không bị tính phí.

Name
target_formats
Type
array
mặc định ["glb"]
Description
Các định dạng để xuất mô hình đã tách. Các định dạng hỗ trợ đối tượng cảnh (glb, obj, fbx, usdz, blend, 3mf) mang mỗi phần như một đối tượng riêng biệt; stl không có khái niệm đối tượng riêng biệt, vì vậy nó hợp nhất mọi phần thành một khối rắn duy nhất được sắp xếp theo layout (yêu cầu 3mf để có các phần có thể chọn riêng biệt trong phần mềm cắt lớp). glb luôn được tạo ra và trả về trong model_urls; liệt kê bất kỳ định dạng nào khác bạn muốn thêm vào.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, blend, 3mf.
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 mô hình nguồn.
- on_plate: Các phần được đặt nằm phẳng và trải rộng trên bàn in, sẵn sàng để cắt lớp — cùng cách sắp xếp như chế độ xem On Plate của ứng dụng web.
Trong cả hai cách sắp xếp, một mảnh vụn sụp hoặc mảnh dạng điểm còn sót lại từ một vết cắt sẽ bị loại bỏ trước khi xuất, vì vậy mọi phần bạn nhận được đều có thể in được. Các định dạng hỗ trợ đối tượng cảnh giữ một đối tượng cho mỗi phần; stl hợp nhất chúng thành một khối rắn duy nhất.
Name
connectors
Type
boolean
mặc định false
Description
Thêm các đầu nối mộng (mortise-and-tenon) tại mỗi vết cắt để các phần in khớp 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 đầu 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 đầu 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
Đầu nối nhô 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.

Giá trị 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ế Độ Lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân thường gặp:
- Thiếu prompt: prompt là bắt buộc khi mode là by_parts hoặc by_color.
- Prompt không mô tả việc tách nào, hoặc quá nhiều phần: by_parts / by_color chấp nhận 1 đến 10 mảnh được nêu tên. Một mô tả yêu cầu giữ mô hình nguyên khối, hoặc nêu tên hơn 10 phần, sẽ bị từ chối. Không 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.
- 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.
- Đầu nối nằm 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 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
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ủa mình. 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
Tính năng 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", vốn không bị ảnh hưởng. Không 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 tác vụ Auto Split.

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 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.

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ Auto Split 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 đã tiêu hao 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 thì không thể xóa được: 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.

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

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

List Auto Split Tasks

Endpoint này cho phép bạn truy xuất 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ỗi trang. Mặc định là 10 mục. Tối đa cho phép là 100 mục; các giá trị lớn hơn sẽ bị 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ề một danh sách có phân trang của Các đối tượng Auto Split Task.

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

Stream an Auto Split Task

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
Mã đị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 The Auto Split Task Objects 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 Retrieve an Auto Split Task, 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 hình là progress, status, started_at và preceding_tasks, còn model_urls, thumbnail_url và part_count 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 dưới đây. Các trường generation-prompt mà các task object khác có (name, object_prompt, texture_prompt, v.v.), model_url đơn lẻ, và texture_urls không bao giờ được điền giá trị cho một lần split và sẽ không được trả về. Các thuộc tính được điền trong khi tác vụ chạy (thumbnail_url, model_urls, các dấu thời gian) luôn hiện diện, rỗ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 của tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo thứ tự 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 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 URL ứng với một định dạng được yêu cầu. Các định dạng hỗ trợ scene object giữ mỗi phần như một object riêng biệt; stl hợp nhất chúng thành một khối rắn duy nhất. 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
  stl
  Type
  string
  Description
  URL có thể tải xuống của mô hình đã split ở định dạng STL. Tất cả các phần được hợp nhất thành một khối rắn duy nhất; hãy yêu cầu 3mf nếu muốn các phần có thể chọn riêng biệt.
- 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.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống của bản xem trước đã render cho mô hình đã split, với mỗi phần có một màu riêng biệt, theo layout được 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 trở đi. 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 mà quá trình split tạo ra. Các định dạng hỗ trợ scene object mang một object cho mỗi phần; stl hợp nhất chúng thành một khối rắn duy nhất, và số lượng vẫn báo cáo theo các phần. Các mảnh vụn bị suy biến (collapsed slivers) mà quá trình phân đoạn không thể biến thành một phần 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
Tiến độ 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 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 toàn bộ tham chiếu đối tượng task_error. Nếu kiểm tra an toàn của nhà cung cấp mô hình từ chối mô hình đầu vào, tác vụ sẽ thất bại với task_error.type là invalid_input và code là provider_content_refused. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số 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í được hoàn lại khi thất bại. Việc xóa một tác vụ trong khi nó vẫn đang PENDING cũng sẽ hoàn lại khoản 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
}