Auto Split API

Chia một mô hình 3D thành các phần có thể in riêng biệt — tự động, theo tên các bộ phận bạn chỉ định, 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 chắc.

Kết quả sau khi chia 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ó dựng lại các phần đã cắt và gán cho mỗi phần một màu vertex phẳng; 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

Tạo tác vụ Auto Split

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

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 được 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) 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 đường cắt. prompt bị bỏ qua.
- by_parts: Cắt theo các bộ phận cấu trúc mà bạn nêu 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 mà bạn nêu tên trong prompt. Yêu cầu đầu vào được tạo ra 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 bộ phận từ đó, vì vậy hãy nêu tên các phần 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. Việc chỉ nêu tên một phần 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ự. Có hai kiểu lỗi: một mô tả yêu cầu không tách gì cả, hoặc nêu tên nhiều hơn 10 phần, sẽ bị từ chối với mã 400 và không 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à vẫn bị tính phí, và phản hồi của nó sẽ mang prompt_ignored: true.

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 về các đố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 được sắp xếp theo layout (hãy yêu cầu 3mf nếu muốn 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; hãy liệt kê thêm bất kỳ định dạng nào khác mà bạn muốn.
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ư mô hình nguồn.
- on_plate: Các phần được đặt phẳng và trải rộng ra trên bàn in, sẵn sàng để cắt lớp — cách sắp xếp giống với chế độ xem On Plate của ứng dụng web.
Ở cả hai cách sắp xếp, một mảnh vụn bị sụp hoặc mảnh giống như một điểm còn sót lại sau khi 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 và lỗ mộng tại mỗi vết cắt để các phần in ra 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 ứng 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 kéo dài bao xa so với bề mặt cắt, tương ứng 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 trường hợp thất bạ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 prompt: prompt là bắt buộc khi mode là by_parts hoặc by_color.
- Prompt mô tả không có sự tách nào, hoặc quá nhiều phần: by_parts / by_color chấp nhận từ 1 đến 10 phần được nêu tên. Một mô tả yêu cầu giữ nguyên mô hình thành một khối, hoặc nêu tên nhiều hơn 10 phần, sẽ bị từ chối. Không có khoản phí nào được tính.
- 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 ra 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 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ủa mình. Các yêu cầu by_parts và by_color cũng dùng chung một 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 có khoản phí nào được tính.

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 Auto Split Task

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

Tham số

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

Kết quả 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 xóa vĩnh viễn một tác vụ Auto Split, bao gồm tất cả các model và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số đường dẫn (Path Parameters)

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: 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, sau đó 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 hoàn lại 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 Auto Split task.

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

Kết quả trả về

Trả về một danh sách được phân trang của The Auto Split Task Objects.

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 một Auto Split Task

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất của Auto Split task cần truyền trực tuyến.

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 task như được trả về bởi Retrieve an Auto Split Task, bao gồm consumed_credits, các dấu thời gian và prompt_ignored; trong khi task đ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 task đạ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 theo 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ỉ chứa các thuộc tính dưới đây. Các trường prompt tạo sinh 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à sẽ không được trả về. Các thuộc tính được điền khi tác vụ đang 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 của 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 URL cho một định dạng được yêu cầu. Các định dạng hỗ trợ đối tượng cảnh sẽ giữ mỗi phần là một đối tượng 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 để có 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 của 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. Xuất hiện 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ợ đối tượng cảnh mang 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, và số lượng vẫn báo cáo theo các phần. Các mảnh vụn bị co sụp 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
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 một 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. Việc xóa một tác vụ khi nó vẫn đang ở trạng thái PENDING cũng sẽ hoàn lại tín dụng.

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
}