Creative Lab — API Fidget Xếp gọn

Biến một ảnh nguồn thành một món đồ chơi fidget xếp gọn có thể in liền một khối: đường viền của chủ thể trở thành một tập hợp các vòng đồng tâm lồng vào nhau, có thể xếp gọn phẳng lại rồi kéo giãn ra, được in thành một khối duy nhất mà không cần lắp ráp.

POST /openapi/creative-lab/fidget-collapsible/v1

Khác với các endpoint Creative Lab khác, endpoint này không có cặp giai đoạn prototype/build — không có các ứng viên trung gian để lựa chọn, vì vậy một tác vụ duy nhất sẽ đưa hình ảnh đi suốt cho đến khi tạo ra mô hình 3D. Các tùy chọn điều khiển hình học mà ứng dụng web hiển thị (kích thước, số lớp, độ rộng khe hở, độ dày thành, độ sâu đùn, độ phồng) cũng không phải là một phần của yêu cầu: mọi tác vụ đều được xây dựng với các giá trị mặc định phía máy chủ giống nhau.

POST/openapi/creative-lab/fidget-collapsible/v1

Tạo tác vụ Fidget có thể xếp gọn

Tạo một mô hình fidget có thể xếp gọn từ ảnh gốc. Tham khảo Đối tượng tác vụ Fidget có thể xếp gọn để biết cấu trúc phản hồi.

Mỗi tác vụ tốn 6 tín dụng và yêu cầu gói trả phí.

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Ảnh gốc để Meshy chuyển đổi thành fidget có thể xếp gọn. Chúng tôi hiện hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Có hai cách để cung cấp ảnh:
- URL truy cập công khai: Một URL có thể truy cập được từ internet công khai.
- Data URI: Một data URI của ảnh được mã hóa base64. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu ảnh được mã hóa base64 của bạn>.
Một đối tượng có đường viền khép kín, rõ ràng sẽ cho kết quả tốt nhất — chính hình bóng (silhouette) sẽ trở thành các vòng nhẫn. Nền phức tạp, nhiều đối tượng riêng biệt, hoặc các hình dạng quá mỏng có thể để lại quá ít diện tích cho các bức tường lồng nhau, và tác vụ sẽ thất bại với lỗi tác vụ.
Name
name
Type
string
Description
Tên tác vụ tùy chọn dùng cho mục đích hiển thị. Tối đa 100 ký tự. Đây chỉ là nhãn của tác vụ; không có gì được khắc lên mô hình.

Kết quả trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ fidget có thể xếp gọn mới được tạo. Hãy thăm dò (poll) endpoint Lấy một tác vụ hoặc đăng ký stream cho đến khi tác vụ đạt trạng thái SUCCEEDED, sau đó tải xuống file STL có thể in được từ model_urls.stl (và, nếu có, file GLB từ model_urls.glb để xem trước).

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 tham số: image_url là bắt buộc.
- Định dạng ảnh không hợp lệ: image_url được cung cấp không thuộc định dạng được hỗ trợ (.jpg, .jpeg, .png, .webp).
- Kích thước ảnh vượt ngoài phạm vi cho phép: Ảnh quá nhỏ, vượt quá kích thước file tối đa, hoặc vượt quá số lượng pixel tối đa.
- URL không thể truy cập: Không thể tải image_url (lỗi 404 hoặc timeout).
- Data URI không hợp lệ: Chuỗi base64 không đúng định dạng.
- Nội dung bị đánh dấu: Ảnh đầu vào bị đánh dấu bởi moderation nội dung nhạy cảm (NSFW).
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
Hoặc tài khoản của bạn đang dùng gói miễn phí — việc tạo tác vụ trên endpoint này yêu cầu gói trả phí — hoặc bạn không có đủ tín dụng.
Name
403 - Forbidden
Description
Ảnh đầu vào bị đánh dấu vì vi phạm quyền sở hữu trí tuệ.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Truy xuất một Collapsible Fidget Task

Truy xuất một collapsible fidget task với một id task hợp lệ. Chỉ những task được tạo thông qua endpoint này mới có thể truy cập được ở đây — một task từ một endpoint Creative Lab khác, hoặc một task được tạo trong ứng dụng web, sẽ trả về 404.

Tham khảo The Collapsible Fidget Task Object để biết cấu trúc phản hồi.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của collapsible fidget task cần truy xuất.

Giá trị trả về

Phản hồi chứa đối tượng collapsible fidget task.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Xóa một Collapsible Fidget Task

Hủy một collapsible fidget task. Nếu task vẫn đang ở trạng thái PENDING, tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại. Các task đã ở trạng thái IN_PROGRESS sẽ bị hủy mà không được hoàn tiền (worker có thể đã đang tiêu tốn tài nguyên). Các task đã đạt đến trạng thái cuối cùng (SUCCEEDED, FAILED, CANCELED) không thể bị hủy.

Tham số đường dẫn

Name
id
Type
path
Description
Định danh duy nhất của collapsible fidget task cần hủy.

Kết quả trả về

Trả về 204 No Content khi thành công với nội dung rỗng.

Các trường hợp lỗi

Name
400 - Bad Request
Description
Task đã ở trạng thái cuối cùng và không thể bị hủy.
Name
404 - Not Found
Description
Task không tồn tại, thuộc về một người dùng khác, hoặc không được tạo thông qua endpoint này.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Truyền trực tiếp thông tin cập nhật cho Tác vụ Fidget có thể gập lại

Truyền trực tiếp các thông tin cập nhật theo thời gian thực cho một tác vụ fidget có thể gập lại thông qua Server-Sent Events (SSE). Một tác vụ không tồn tại, hoặc không được tạo thông qua endpoint này, sẽ phát ra một payload event: error duy nhất với status_code: 404 và đóng luồng dữ liệu.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ fidget có thể gập lại cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng các đối tượng tác vụ Fidget có thể gập lại dưới dạng Server-Sent Events. Đối với các tác vụ ở trạng thái 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.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

GET/openapi/creative-lab/fidget-collapsible/v1

Danh sách tác vụ Fidget có thể gập lại

Truy xuất danh sách phân trang các tác vụ fidget có thể gập lại của bạn. Chỉ những tác vụ được tạo qua endpoint này mới được bao gồm.

Tham số truy vấn

Name
page_num
Type
integer
mặc định 1
Description
Số trang cho phân trang.
Name
page_size
Type
integer
mặc định 10
Description
Giới hạn kích thước trang. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
mặc định -created_at
Description
Trường để sắp xếp theo. 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ề danh sách phân trang của đối tượng tác vụ fidget có thể gập lại.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Đối tượng Nhiệm vụ Fidget Có thể Xếp gọn (Collapsible Fidget Task)

Đối tượng Collapsible Fidget Task là một đơn vị công việc mà Meshy theo dõi để biến một ảnh nguồn thành một mô hình fidget có thể xếp gọn, in trực tiếp không cần lắp ráp. Đây là một nhiệm vụ một giai đoạn: không có prototype nào để nối tiếp, và phần silhouette trung gian không phải là một phần của phản hồi.

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho nhiệm vụ. Trong khi 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 nhiệm 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 nhiệm vụ. Giá trị là creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Tên nhiệm vụ được cung cấp khi nhiệm vụ được tạo. Là chuỗi rỗng nếu không có tên nào được cung cấp.
Name
status
Type
string
Description
Trạng thái của nhiệm vụ. Các giá trị có thể là một trong số PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Tiến trình của nhiệm vụ. Nếu nhiệm vụ chưa được bắt đầu, thuộc tính này sẽ là 0. Khi nhiệm vụ đã thành công, giá trị này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm nhiệm vụ được tạo, tính bằng milliseconds.
Một dấu thời gian biểu thị số milliseconds đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023, 12:00:00 PM GMT được biểu thị là 1693569600000. Điều này áp dụng cho tất cả các dấu thời gian trong Meshy API.
Name
started_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm nhiệm vụ được bắt đầu, tính bằng milliseconds. Nếu nhiệm vụ chưa được bắt đầu, thuộc tính này sẽ là null.
Name
finished_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm nhiệm vụ hoàn thành, tính bằng milliseconds. Nếu nhiệm vụ chưa hoàn thành, thuộc tính này sẽ là null.
Name
expires_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm kết quả nhiệm vụ hết hạn, tính bằng milliseconds.
Name
preceding_tasks
Type
integer
Description
Số lượng nhiệm vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái nhiệm vụ là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các nhiệm 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ố tín dụng đã bị tiêu thụ bởi nhiệm vụ này. Xuất hiện 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).
Name
model_urls
Type
object
Description
URL có thể tải xuống cho mô hình 3D được tạo ra. Được điền khi nhiệm vụ đã SUCCEEDED: stl luôn xuất hiện, glb chỉ xuất hiện khi việc kết xuất bản xem trước (preview render) thành công.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống cho tệp STL. Đây là sản phẩm có thể in — gửi trực tiếp đến phần mềm cắt lớp.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống cho tệp GLB, dùng để xem trước mô hình trong trình xem 3D. Màu sắc của tệp này chỉ để xem trước: STL không chứa màu sắc, và một fidget được in ra sẽ có màu từ vật liệu in (filament). GLB được cung cấp trên cơ sở nỗ lực tối đa: khi bản kết xuất xem trước không có sẵn, khóa này sẽ được bỏ qua hoàn toàn khỏi model_urls, vì vậy hãy đọc nó một cách phòng thủ — stl là sản phẩm bàn giao và luôn xuất hiện trên một nhiệm vụ SUCCEEDED.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}