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

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.

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 mà bạn muốn tách mô hình. 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, hoặc latest). Các mô hình low-poly và Smart Topology (meshy-t2) không được hỗ trợ.

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 sẽ 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, 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 lỗi 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 tách, bằng bất kỳ ngôn ngữ nào. Meshy sẽ đọc từ 1 đến 10 tên bộ 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 (tách thành tượng và đế), hoặc head, torso, left arm, right arm, legs (đầu, thân, tay trái, tay phải, chân). Tối đa 600 ký tự. Có hai chế độ lỗi: một mô tả đọc như một lệnh tách nhưng chỉ nêu tên ít hơn hai phần (ví dụ split into individual parts) sẽ bị từ chối với lỗi 400 và không bị tính phí; một mô tả mà Meshy hoàn toàn không thể đọc được sẽ tự động chuyển về auto, tác vụ vẫn chạy và bị tính phí, và phản hồi của nó sẽ mang giá trị 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. 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 mà bạn muốn.
Các giá trị khả dụng: glb, obj, fbx, 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 gốc.
- on_plate: Các phần được đặt phẳng và dàn ra trên bàn in, sẵn sàng để cắt lát — cùng cách sắp xếp như chế độ xem On Plate của ứng dụng web.
Trong cả hai bố cục, các tệp xuất ra đều chỉ chứa một đối tượng cho mỗi phần và không có gì khác: một mảnh mỏng bị co lại hoặc mảnh giống đ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 tìm thấy trong tệp đều có thể in được.
Name
connectors
Type
boolean
mặc định false
Description
Thêm các đầu nối kiểu mộng âm-dươ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 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 khỏi bề mặt cắt bao xa, 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ế độ 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 prompt: prompt là bắt buộc khi mode là by_parts hoặc by_color.
- Prompt nêu tên ít hơn hai phần: by_parts / by_color cần ít nhất hai mảnh được nêu tên (ví dụ head, torso, base); một hướng dẫn chung chung như split into individual parts 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.
- Đầu vào có texture: Mô hình đầu vào có texture. Hiện tại chỉ các mô hình không có texture mới được hỗ trợ.
- 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.
- Đầu 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
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", tính năng này 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.cn/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.cn/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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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.cn/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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/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.cn/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.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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
}

Đối tượng Auto Split Task

Một Auto Split task chỉ mang các thuộc tính dưới đây. Các trường generation-prompt mà những đối tượng task 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 task chạy (thumbnail_url, model_urls, các dấu thời gian) luôn có mặt, để 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 task. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) làm chi tiết triển khai cho id của task, 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 task. Giá trị là print-split.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho model đã được split, mỗi URL ứng với một định dạng được yêu cầu. 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 cho model đã split ở định dạng GLB.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống cho model đã split ở định dạng OBJ.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống cho model đã split ở định dạng FBX.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống cho model đã split ở định dạng USDZ.
- Name
  blend
  Type
  string
  Description
  URL có thể tải xuống cho model đã split ở định dạng Blender.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống cho model đã split ở định dạng 3MF.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống cho bản xem trước được render của model đã 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 bộ phận nào, nên Meshy tự động split model thay vì theo prompt — tên các bộ phận trong kết quả là do Meshy đặt, không phải của bạn. Có mặt từ trạng thái PENDING trở đi. Bị bỏ qua đối với các task auto và bất cứ khi nào prompt được tuân theo.
Name
part_count
Type
integer
Description
Số lượng bộ phận có thể in được trong model đã split — mỗi đối tượng trong các tệp xuất ra tương ứng với một bộ 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
Tiến trình của task. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0. Khi task đã thành công, giá trị này sẽ trở thành 100.
Name
status
Type
string
Description
Trạng thái của task. 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 task đứng trước.
Giá trị của trường này chỉ có ý nghĩa nếu trạng thái task là PENDING.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi task được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi task được bắt đầu, tính bằng mili giây. Nếu task 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 task hoàn thành, tính bằng mili giây. Nếu task 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 task thất bại. Xem Lỗi để biết đầy đủ tài liệu tham khảo về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng đã tiêu thụ bởi task này. Luôn có mặt: 10 khi task đã được chấp nhận, và 0 đối với các task FAILED vì khoản phí sẽ được hoàn lại khi thất bại. Việc xóa một task 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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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
}