lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

Creative Lab Collapsible Fidget API

Biến một bức ảnh thành đồ chơi fidget có thể gập lại, in liền khối (print-in-place) chỉ trong một tác vụ. Đường viền (silhouette) của chủ thể trở thành các vòng tròn đồng tâm lồng vào nhau, có thể gập phẳng lại và kéo giãn ra. Đồ chơi được in thành một khối duy nhất, không cần lắp ráp.

  • 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ó giai đoạn prototype và build riêng biệt. Không có các ảnh ứng viên để lựa chọn, vì vậy một tác vụ duy nhất sẽ biến ảnh thành mô hình 3D.

Yêu cầu cũng không có cài đặt hình học. Ứng dụng web cho phép bạn đặt kích thước, số lớp, độ rộng khe hở, độ dày thành, độ sâu đùn và độ phồng. Mọi tác vụ API đều sử dụng cùng các giá trị mặc định cho các thông số này.

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. Để biết các trường của tác vụ, xem Đối tượng tác vụ Collapsible Fidget.

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

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"
}

Tham số

  • Name
    image_url
    Type
    string
    Bắt buộc
    Description

    Bức ảnh để biến thành collapsible fidget, dưới dạng URL công khai hoặc data URI (data:image/jpeg;base64,<dữ liệu ảnh được mã hóa base64 của bạn>).

    Hình ảnh phải là file JPG, JPEG, PNG, hoặc WebP có kích thước tối đa 20 MB.

    Đường viền của chủ thể sẽ trở thành các vòng nhẫn, vì vậy một chủ thể có đường viền khép kín, rõ ràng sẽ cho kết quả tốt nhất. Nền phức tạp, nhiều chủ thể riêng biệt, hoặ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. Trong trường hợp đó, tác vụ sẽ thất bại.

  • Name
    name
    Type
    string
    Description

    Tên của tác vụ, tối đa 100 ký tự. Tên này sẽ được trả về trong trường name của tác vụ, và Meshy không khắc tên này lên mô hình. Tên quá dài sẽ trả về 400.

Giá trị trả về

Trường result chứa ID của tác vụ mới. Lấy tác vụ hoặc stream nó cho đến khi status là SUCCEEDED. Sau đó tải xuống file STL có thể in từ model_urls.stl. Để xem trước mô hình, tải xuống file GLB từ model_urls.glb khi nó xuất hiện.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể chạy. Ví dụ:

    • image_url bị thiếu.
    • Hình ảnh không phải là file JPG, JPEG, PNG, hoặc WebP.
    • Hình ảnh quá nhỏ, vượt quá 20 MB, hoặc vượt quá số lượng pixel tối đa.
    • Meshy không thể tải xuống hình ảnh, ví dụ vì URL trả về 404 hoặc hết thời gian chờ.
    • Data URI không phải base64 hợp lệ.
    • Hình ảnh bị đánh dấu là nội dung nhạy cảm (NSFW).

    Thông báo lỗi sẽ cho biết vấn đề nào đã được phát hiện. Sửa yêu cầu, sau đó gửi lại.

  • Name
    401 - Unauthorized
    Description

    Thiếu hoặc không hợp lệ khóa API. Kiểm tra header Authorization.

  • Name
    402 - Payment Required
    Description

    Một trong những điều sau đây áp dụng:

    • Tài khoản không có đủ tín dụng.
    • Khóa API, không gian làm việc, hoặc thành viên đã đạt giới hạn tín dụng.
    • Tài khoản đang dùng gói miễn phí.

    Kiểm tra tín dụng và gói của bạn, sau đó thử lại.

  • Name
    403 - Forbidden
    Description

    Nhóm của bạn đã bật tính năng Lọc IP, và Meshy đã đánh dấu hình ảnh này do vi phạm sở hữu trí tuệ của bên thứ ba. Hãy gửi hình ảnh mà bạn có quyền sử dụng.

  • Name
    429 - Too Many Requests
    Description

    Một trong những giới hạn sau đã đạt tới:

    • Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Đợi vài giây, sau đó thử lại. Xem Giới hạn tốc độ.
    • Có quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Đợi một số tác vụ hoàn thành, sau đó thử lại.
    • Với gói không giới hạn nhưng không còn tín dụng, bạn đã đạt số lượng tác vụ có thể chạy mà không cần tín dụng. Đợi một tác vụ hoàn thành, hoặc nạp thêm tín dụng.
  • Name
    500 - Internal Server Error
    Description

    Meshy gặp lỗi máy chủ, ví dụ vì không thể chạy kiểm tra sở hữu trí tuệ trên hình ảnh. Meshy không tạo tác vụ, và hoàn lại bất kỳ khoản tín dụng nào đã tính phí. Thử lại yêu cầu.

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

Lấy tác vụ Collapsible Fidget

Trả về một tác vụ Collapsible Fidget. Chỉ các tác vụ được tạo bằng endpoint này mới được trả về. Một tác vụ từ endpoint Creative Lab khác, hoặc một tác vụ được tạo trong ứng dụng web, sẽ trả về 404.

Để biết các trường dữ liệu, xem Đối tượng tác vụ Collapsible Fidget.

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=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo.

Giá trị trả về

Đối tượng tác vụ Collapsible Fidget.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    id không phải là ID tác vụ hợp lệ. Hãy gửi ID result từ phản hồi tạo.

  • Name
    403 - Forbidden
    Description

    Nhóm của bạn đã bật tính năng Lọc IP, và Meshy đã gắn cờ hình ảnh của tác vụ này vì sở hữu trí tuệ của bên thứ ba. Các nhóm dùng gói Enterprise sẽ không gặp lỗi này. Hãy tạo tác vụ từ hình ảnh mà bạn có quyền sử dụng.

  • Name
    404 - Not Found
    Description

    Không có tác vụ Collapsible Fidget nào với ID này thuộc về tài khoản của bạn, hoặc tác vụ đó không được tạo bằng endpoint này. Hãy kiểm tra lại ID.

  • Name
    500 - Internal Server Error
    Description

    Meshy không thể chạy kiểm tra sở hữu trí tuệ. Hãy thử lại yêu cầu.

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

Xóa một tác vụ Collapsible Fidget

Hủy một tác vụ Collapsible Fidget. Hủy một tác vụ PENDING sẽ hoàn lại tín dụng của tác vụ đó. Một tác vụ IN_PROGRESS sẽ bị hủy mà không được hoàn tín dụng, vì một worker đã bắt đầu xử lý tác vụ đó. Một tác vụ có trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) không thể bị hủ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).

Tham số đường dẫn

  • Name
    id
    Type
    path
    Description

    ID của tác vụ cần hủy.

Giá trị trả về

204 No Content với nội dung rỗng.

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

  • Name
    400 - Bad Request
    Description

    Một trong các trường hợp sau áp dụng:

    • id không phải là một ID tác vụ hợp lệ. Hãy gửi ID result từ phản hồi tạo tác vụ.
    • Tác vụ đã có trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED), nên không thể bị hủy.
  • Name
    404 - Not Found
    Description

    Không có tác vụ Collapsible Fidget nào với ID này thuộc về tài khoản của bạn, hoặc tác vụ này không được tạo bằng endpoint này. Hãy kiểm tra lại ID.

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

Truyền trực tiếp tác vụ Collapsible Fidget

Truyền trực tiếp các cập nhật của tác vụ Collapsible Fidget dưới dạng Server-Sent Events (SSE). Nếu tác vụ không tồn tại hoặc không được tạo bằng endpoint này, luồng sẽ gửi một sự kiện error với status_code: 404 rồi đóng lại.

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 following PENDING frame is shortened 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=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo.

Giá trị trả về

Một luồng đối tượng tác vụ Collapsible Fidget. Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, giống như Lấy thông tin tác vụ Collapsible Fidget trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra của nó vẫn còn trống (null, [], hoặc {}), và finished_at là null.

Nếu IP Filtering chặn kết quả của tác vụ, luồng sẽ gửi một sự kiện error thay thế, kèm status_code mà một yêu cầu get sẽ trả về.

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

Liệt kê các tác vụ Collapsible Fidget

Trả về các tác vụ Collapsible Fidget của bạn, mỗi lần một trang. Chỉ các tác vụ được tạo bằng endpoint này mới được bao gồm.

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=***"
    }
  }
]

Tham số truy vấn

  • Name
    page_num
    Type
    integer
    mặc định 1
    Description

    Trang cần trả về, từ 1 đến 255. 0 trả về trang đầu tiên. Giá trị ngoài khoảng 0 đến 255 sẽ trả về 400.

  • Name
    page_size
    Type
    integer
    mặc định 10
    Description

    Số lượng tác vụ trên mỗi trang, tối đa 100. Giá trị từ 101 đến 255 sẽ trả về 100 tác vụ, và 0 sẽ sử dụng giá trị mặc định. Giá trị ngoài khoảng 0 đến 255 sẽ trả về 400.

  • Name
    sort_by
    Type
    string
    mặc định -created_at
    Description

    Thứ tự sắp xếp.

    Các giá trị khả dụng:

    • -created_at: mới nhất trước
    • +created_at: cũ nhất trước

Giá trị trả về

Một mảng các đối tượng tác vụ Collapsible Fidget.

Đối tượng tác vụ Collapsible Fidget

Một tác vụ Collapsible Fidget biến một bức ảnh thành mô hình fidget có thể gập lại, in liền khối. Đây là tác vụ một giai đoạn, nên không có tác vụ nguyên mẫu nào để nối chuỗi từ đó. Phản hồi không bao gồm hình bóng (silhouette) mà Meshy tạo ra trong quá trình xử lý.

Thuộc tính

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=***"
  }
}
  • Name
    id
    Type
    string
    Description

    ID của tác vụ. Đừng phụ thuộc vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại tác vụ, luôn là creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    name mà bạn đã gửi khi tạo tác vụ, hoặc "" nếu bạn không gửi.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ.

    Các giá trị khả dụng:

    • PENDING: đang chờ trong hàng đợi
    • IN_PROGRESS: đang tạo kết quả
    • SUCCEEDED: trạng thái cuối, có kết quả
    • FAILED: trạng thái cuối, kèm lý do trong task_error
    • CANCELED: trạng thái cuối, không có kết quả
  • Name
    progress
    Type
    integer
    Description

    Phần trăm công việc đã hoàn thành, từ 0 đến 100. Giá trị này là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.

  • Name
    created_at
    Type
    timestamp
    Description

    Thời điểm tác vụ được tạo, tính bằng mili-giây Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Thời điểm một worker bắt đầu tác vụ, tính bằng mili-giây Unix. Là null cho đến khi đó.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm tác vụ đạt trạng thái cuối, tính bằng mili-giây Unix. Là null cho đến khi đó.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm kết quả của tác vụ hết hạn, tính bằng mili-giây Unix. Giá trị này là 3 ngày sau finished_at, hoặc 3 ngày sau created_at cho đến khi tác vụ hoàn tất. Đối với tài khoản Enterprise, vốn giữ kết quả API vô thời hạn, giá trị này là khoảng 100 năm sau. Xem Lưu giữ tài nguyên.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Vị trí của tác vụ trong hàng đợi khi tác vụ đang ở trạng thái PENDING. 1 nghĩa là tác vụ sẽ bắt đầu tiếp theo. Là 0 sau khi tác vụ rời khỏi hàng đợi, và luôn là 0 trong kết quả danh sách.

  • Name
    task_error
    Type
    object
    Description

    Lý do tác vụ thất bại. Là null trừ khi status là FAILED. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng bị tính phí cho tác vụ, sau khi hoàn tiền (nếu có). Một yêu cầu trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại có giá trị 0, vì Meshy sẽ hoàn lại tín dụng cho tác vụ đó. Việc hủy chỉ hoàn tiền cho tác vụ khi tác vụ đang ở trạng thái PENDING. Nếu Meshy không thể đọc được khoản phí, phản hồi get hoặc stream sẽ bỏ qua trường này, và một yêu cầu danh sách sẽ trả về 500. Trong trường hợp đó, hãy thử lại yêu cầu.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống cho mô hình 3D, trống cho đến khi tác vụ thành công. Một tác vụ thành công luôn có stl, và chỉ có glb nếu Meshy đã kết xuất bản xem trước.

    • Name
      stl
      Type
      string
      Description

      URL tải xuống cho tệp STL, là tệp dùng để in. Bạn có thể mở trực tiếp tệp này trong phần mềm cắt lớp.

    • Name
      glb
      Type
      string
      Description

      URL tải xuống cho tệp GLB để xem trước mô hình trong trình xem 3D. Màu sắc của tệp này chỉ dùng để xem trước. Tệp STL không có màu, nên fidget được in ra sẽ có màu từ sợi nhựa in.

      Nếu Meshy không thể kết xuất bản xem trước, model_urls sẽ không có khóa glb, vì vậy hãy kiểm tra sự tồn tại của khóa này trước khi đọc nó. Một tác vụ SUCCEEDED luôn có stl.