Creative Lab — API đồ chơi Fidget gấp gọn (Collapsible Fidget)

Biến một bức ảnh nguồn thành đồ chơi fidget gấp gọn có thể in trực tiếp mà không cần lắp ráp: đườ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ể gấp phẳng lại và kéo giãn ra, được in liền một khối duy nhất.

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

Không giống như 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 quá trình 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ụ Collapsible Fidget

Tạo một mô hình collapsible fidget từ một bức ảnh nguồn. Tham khảo The Collapsible Fidget Task Object để biết hình dạng 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 nguồn để Meshy biến thành một collapsible fidget. 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 hình ảnh:
- URL có thể truy cập công khai: Một URL có thể truy cập được từ internet công cộng.
- Data URI: Một data URI mã hóa base64 của hình ảnh. Ví dụ về một data URI: data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>.
Một chủ thể có một đường viền rõ ràng, khép kín sẽ cho kết quả tốt nhất — đường viền (silhouette) chính là thứ trở thành các vòng nhẫn. Bối cảnh phức tạp, nhiều chủ thể 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 một lỗi tác vụ.
Name
name
Type
string
Description
Tên tác vụ tùy chọn cho mục đích hiển thị. Tối đa 100 ký tự. Đây chỉ là nhãn tác vụ; không có gì được khắc lên mô hình.

Giá trị trả về

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

Các chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không thể 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 hình ảnh không hợp lệ: image_url được cung cấp không phải là định dạng được hỗ trợ (.jpg, .jpeg, .png, .webp).
- Kích thước hình ảnh nằm ngoài phạm vi: Hình ảnh quá nhỏ, vượt quá kích thước tệp 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 xuống image_url (404 hoặc timeout).
- Data URI không hợp lệ: Chuỗi base64 bị sai định dạng.
- Nội dung bị gắn cờ: Hình ảnh đầu vào đã bị gắn cờ bởi moderation 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 ở 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 đủ tín dụng.
Name
403 - Forbidden
Description
Hình ảnh đầu vào đã bị gắn cờ vì vi phạm sở hữu trí tuệ.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.

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 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 tại đâ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 Đối tượng Collapsible Fidget Task để 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 Tác vụ Fidget Collapsible

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

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

Name
id
Type
path
Description
Định danh duy nhất của tác vụ fidget collapsible 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 thất bại

Name
400 - Bad Request
Description
Tác vụ đã ở trạng thái cuối cùng và không thể bị hủy.
Name
404 - Not Found
Description
Tác vụ không tồn tại, thuộc về 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 Tác vụ Fidget có thể gập lại

Truyền trực tiếp các 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. Mỗi khung dữ liệu mang theo đối tượng tác vụ đầy đủ cho giai đoạn đó — cùng cấu trúc mà endpoint Get trả về — vì vậy khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra đơn giản là chưa được điền (null, [] hoặc {}) và finished_at là null.

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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
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

Liệt kê các 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 thông 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 theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự 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 Task Fidget Có Thể Gập Lại

Đối tượng Task Fidget Có Thể Gập Lại (Collapsible Fidget Task) là một đơn vị công việc mà Meshy theo dõi để chuyển đổi một ảnh nguồn thành mô hình fidget có thể gập lại in liền một khối (print-in-place). Đây là một tác vụ đơn giai đoạn: không có prototype để nối chuỗi, và đường viền trung gian (silhouette) không phải là một phần của phản hồi.

Thuộc tính

Name
id
Type
string
Description
Mã đị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à creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Tên tác vụ được cung cấp khi tác 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 tác vụ. Các giá trị có thể có là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
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
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng mili giây.
Dấu thời gian biểu thị số mili giây đã 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 lúc 12:00:00 CH 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 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à null.
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à null.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả của tác vụ hết hạn, tính bằng mili giây.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái tác vụ là PENDING.
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 đầy đủ tham chiếu đố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. Xuất hiện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho mô hình 3D đã tạo. Được điền khi tác vụ đã SUCCEEDED: stl luôn xuất hiện, glb chỉ xuất hiện khi việc render xem trước thành công.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống của 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 của tệp GLB, để xem trước mô hình trong trình xem 3D. Màu sắc của nó chỉ để xem trước: STL không mang màu sắc, và một fidget được in sẽ nhận màu từ sợi nhựa in (filament). GLB được cung cấp trên cơ sở nỗ lực tốt nhất (best-effort): khi việc render xem trước không khả dụng, khóa này sẽ bị bỏ hoàn toàn khỏi model_urls, vì vậy hãy đọc nó một cách thận trọng — stl là sản phẩm bàn giao và luôn xuất hiện trên một tác 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=***"
  }
}