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ợ

API Fidget Pixel của Creative Lab

Biến một bức ảnh thành bảng fidget pixel-art đa màu, có thể in 3D qua hai giai đoạn. Một tác vụ prototype biến bức ảnh thành một hình ảnh pixel-art. Một tác vụ build biến hình ảnh đó thành các mảnh ghép khớp với nhau trong một tệp 3MF duy nhất, và lấy ID của tác vụ prototype làm input_task_id.

  • POST /openapi/creative-lab/fidget-pixel/v1/prototype
  • POST /openapi/creative-lab/fidget-pixel/v1/build

Cả hai endpoint POST đều yêu cầu gói trả phí. Một yêu cầu từ tài khoản gói miễn phí sẽ trả về 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Tạo một tác vụ nguyên mẫu Fidget Pixel

Tạo ra một hình ảnh pixel-art từ một bức ảnh. Để tạo các mảnh ghép, hãy truyền ID của tác vụ này tới endpoint build dưới dạng input_task_id. Để biết các trường của tác vụ, xem Đối tượng tác vụ nguyên mẫu Fidget Pixel.

Nếu bạn không thích hình ảnh, hãy tạo một tác vụ nguyên mẫu khác. Mỗi tác vụ được tính phí riêng.

Request

POST
/openapi/creative-lab/fidget-pixel/v1/prototype
# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype \
  -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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Tham số

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

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

    Hình ảnh phải là tệp JPG, JPEG, PNG, hoặc WebP có kích thước tối đa 20 MB. Meshy phát hiện định dạng từ dữ liệu hình ảnh, không phải từ phần mở rộng tệp trong URL. URL không có phần mở rộng vẫn hoạt động, và Meshy sẽ theo các chuyển hướng (redirect).

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

    Nội dung mà bức ảnh thể hiện, điều này sẽ quyết định phong cách pixel-art. Hai phong cách này trông khác biệt rõ rệt. Bất kỳ giá trị nào khác sẽ trả về 400.

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

    • person: một người, trong ảnh chân dung hoặc ảnh toàn thân. Meshy sẽ vẽ một pixel sprite theo phong cách chibi.
    • other: bất kỳ chủ thể nào khác, ví dụ như thú cưng, vật thể, linh vật, logo, hoặc phong cảnh. Meshy sẽ vẽ một biểu tượng pixel theo phong cách bead-art.
  • Name
    name
    Type
    string
    Description

    Tên cho tác vụ, tối đa 100 ký tự. Tên này sẽ xuất hiện trong trường name của tác vụ. Tên dài hơn sẽ trả về 400.

Giá trị trả về

Trường result chứa ID của tác vụ nguyên mẫu mới. Lấy tác vụ hoặc theo dõi dạng luồng (stream) cho đến khi status là SUCCEEDED. Sau đó truyền ID này tới endpoint build dưới dạng input_task_id.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể thực thi. Ví dụ:

    • Thiếu image_url hoặc type.
    • type không phải là person hoặc other.
    • Hình ảnh không phải là tệp 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 là 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. Hãy sửa yêu cầu, sau đó gửi lại.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header Authorization.

  • Name
    402 - Payment Required
    Description

    Một trong các điều sau đây xảy ra:

    • 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 ở gói miễn phí.

    Hãy 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 Lọc IP (IP Filtering), và Meshy đã đánh dấu hình ảnh vì liên quan đến quyền sở hữu trí tuệ của bên thứ ba. Hãy gửi một hình ảnh mà bạn có quyền sử dụng.

  • Name
    429 - Too Many Requests
    Description

    Một trong các giới hạn sau đã đạt đến:

    • Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Hãy đợi vài giây, sau đó thử lại. Xem Giới hạn tốc độ.
    • Quá nhiều tác vụ của bạn đang xếp hàng chờ hoặc đang chạy. Hãy đợi một số tác vụ hoàn thành, sau đó thử lại.
    • Trên gói không giới hạn nhưng không còn tín dụng, bạn đã đạt đến số lượng tác vụ có thể chạy mà không cần tín dụng. Hãy đợ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 quyền 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í. Hãy thử lại yêu cầu.

POST/openapi/creative-lab/fidget-pixel/v1/build

Tạo tác vụ xây dựng Fidget Pixel

Tạo ra các mảnh ghép có thể in 3D từ một tác vụ nguyên mẫu (prototype) đã thành công. Meshy lấy mẫu hình ảnh pixel art lên lưới và giảm xuống còn tối đa color_count màu. Mỗi ô của đối tượng trở thành một mảnh ghép lồng vào nhau, và phần nền sẽ không được in.

Kết quả là một tệp 3MF đa màu duy nhất, sẵn sàng để in màu. Mỗi mảnh ghép có phần thân màu xám và phần đỉnh mang màu của pixel tương ứng. Để biết các trường của nó, xem Đối tượng tác vụ xây dựng Fidget Pixel.

Request

POST
/openapi/creative-lab/fidget-pixel/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Tham số

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

    ID của tác vụ nguyên mẫu cần xây dựng. Nó phải là một tác vụ do tài khoản của bạn tạo bằng POST /openapi/creative-lab/fidget-pixel/v1/prototype, với trạng thái SUCCEEDED.

    Một ID không phải là một trong các tác vụ nguyên mẫu Fidget Pixel của bạn từ API sẽ trả về 404, kể cả một nguyên mẫu được tạo trong ứng dụng web.

  • Name
    name
    Type
    string
    Description

    Tên cho tác vụ, tối đa 100 ký tự. Nó sẽ được trả về trong trường name của tác vụ. Một tên dài hơn sẽ trả về 400.

options

Cài đặt cho hình dạng và kích thước của các mảnh ghép. Mỗi trường đều có giá trị mặc định, vì vậy bạn chỉ cần gửi những trường mà bạn muốn thay đổi. Giá trị 0 sẽ sử dụng giá trị mặc định của trường đó. Đây là các cài đặt giống như trong ứng dụng web Creative Lab. Các cài đặt hình dạng khác được cố định, và Meshy đặt chúng dựa trên shape và piece_size_mm.

  • Name
    shape
    Type
    string
    mặc định square
    Description

    Hình dạng mặt đáy của mỗi mảnh ghép. Bất kỳ giá trị nào khác sẽ trả về 400.

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

    • square: các mảnh ghép hình vuông trên lưới hình vuông
    • hex: các mảnh ghép hình lục giác trên lưới hình lục giác, với piece_size_mm được đặt là 6 hoặc 8
  • Name
    grid_size
    Type
    integer
    mặc định 32
    Description

    Số ô lưới dọc theo mỗi cạnh của bảng, 16 hoặc 32. Bất kỳ giá trị nào khác sẽ trả về 400. Lưới 32 giữ được nhiều chi tiết hơn. Lưới 16 cho ra ít mảnh ghép hơn với cùng kích thước, nên bảng sẽ rộng bằng khoảng một nửa.

  • Name
    piece_size_mm
    Type
    integer
    mặc định 8
    Description

    Độ dài cạnh của mỗi mảnh ghép tính bằng milimét, 6, 8, hoặc 10. Bất kỳ giá trị nào khác sẽ trả về 400. Cùng với grid_size, nó xác định kích thước của bảng in ra. Ví dụ, một lưới 32 với các mảnh ghép 8 mm sẽ có kích thước khoảng 26,5 cm mỗi cạnh.

    10 không hoạt động với hex và sẽ trả về 400, vì mặt nghiêng của hình lục giác sẽ bị hẫng trên hầu hết các máy in FDM dành cho người dùng phổ thông.

  • Name
    color_count
    Type
    integer
    mặc định 8
    Description

    Số lượng màu tối đa trong bảng màu pixel art, từ 1 đến 8. Giá trị ngoài phạm vi này sẽ trả về 400. Để in, bạn cần tối đa color_count cộng thêm một sợi nhựa in, một cho mỗi màu và một cho các phần thân màu xám.

  • Name
    piece_height_mm
    Type
    integer
    mặc định 15
    Description

    Chiều cao của mỗi mảnh ghép tính bằng milimét, từ 10 đến 80. Giá trị ngoài phạm vi này sẽ trả về 400.

output

Cài đặt cho tệp kết quả.

  • Name
    format
    Type
    string
    mặc định 3mf
    Description

    Định dạng tệp của kết quả. Bất kỳ giá trị nào khác sẽ trả về 400.

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

    • 3mf: một tệp model.3mf đa màu duy nhất, được trả về trong model_urls.3mf

Giá trị trả về

Trường result chứa ID của tác vụ xây dựng mới. Lấy tác vụ hoặc theo dõi dạng luồng cho đến khi status là SUCCEEDED. Sau đó tải xuống tệp 3MF từ model_urls.3mf.

Các trường hợp thất bại

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể thực hiện. Ví dụ:

    • input_task_id bị thiếu hoặc không phải là một ID tác vụ hợp lệ.
    • Trạng thái của tác vụ nguyên mẫu không phải là SUCCEEDED. Nếu nó vẫn đang chạy, hãy chờ và thử lại. Nếu nó thất bại hoặc bị hủy, hãy tạo một tác vụ nguyên mẫu mới.
    • Tác vụ nguyên mẫu đã thành công nhưng không có hình ảnh. Hãy tạo một tác vụ nguyên mẫu mới.
    • Một trường trong options nằm ngoài các giá trị được cho phép, ví dụ grid_size khác 16 hoặc 32.
    • piece_size_mm là 10 và shape là hex. Các mảnh ghép hình lục giác chỉ có kích thước 6 và 8 mm.
    • output.format không phải là 3mf.

    Thông báo lỗi sẽ cho biết vấn đề nào đã được phát hiện.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header Authorization.

  • Name
    402 - Payment Required
    Description

    Một trong các trường hợp sau á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 đến giới hạn tín dụng.
    • Tài khoản đang ở gói miễn phí.

    Hãy 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 Lọc IP, và Meshy đã gắn cờ hình ảnh của tác vụ nguyên mẫu vì liên quan đến quyền sở hữu trí tuệ của bên thứ ba. Hãy tạo một tác vụ nguyên mẫu từ một hình ảnh mà bạn có quyền sử dụng.

  • Name
    404 - Not Found
    Description

    input_task_id không khớp với bất kỳ tác vụ nguyên mẫu Fidget Pixel nào mà tài khoản của bạn đã tạo bằng API. Một nguyên mẫu được tạo trong ứng dụng web cũng sẽ trả về 404. Hãy gửi ID result từ phản hồi tạo nguyên mẫu.

  • Name
    429 - Too Many Requests
    Description

    Một trong các giới hạn sau đã đạt đến:

    • Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Hãy chờ vài giây rồi thử lại. Xem Giới hạn tốc độ.
    • Quá nhiều tác vụ của bạn đang xếp hàng chờ hoặc đang chạy. Hãy chờ một số tác vụ hoàn thành rồi thử lại.
    • Trên gói không giới hạn nhưng đã hết tín dụng, bạn đã đạt đến số lượng tác vụ có thể chạy mà không cần tín dụng. Hãy chờ 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 quyền sở hữu trí tuệ đối với hình ảnh của tác vụ nguyên mẫu. Meshy sẽ không tạo tác vụ, và hoàn lại bất kỳ khoản tín dụng nào đã bị trừ. Hãy thử lại yêu cầu.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Lấy một tác vụ Fidget Pixel

Trả về một tác vụ prototype hoặc build. Đường dẫn phải khớp với giai đoạn của tác vụ. Một tác vụ build được yêu cầu thông qua /prototype/:id sẽ trả về 404, và một tác vụ prototype được yêu cầu thông qua /build/:id cũng vậy.

Để biết các trường dữ liệu, xem Đối tượng tác vụ prototype của Fidget Pixel và Đối tượng tác vụ build của Fidget Pixel.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

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

Giá trị trả về

Đối tượng tác vụ prototype hoặc đối tượng tác vụ build, tương ứng với giai đoạn trong đường dẫn.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

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

  • Name
    403 - Forbidden
    Description

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

  • Name
    404 - Not Found
    Description

    Không có tác vụ Fidget Pixel nào với ID này thuộc tài khoản của bạn, hoặc giai đoạn của tác vụ không khớp với đường dẫn. Hãy kiểm tra ID, và sử dụng /prototype hoặc /build để khớp với tác vụ.

  • 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-pixel/v1/(prototype|build)/:id

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

Hủy một tác vụ Fidget Pixel. Việc 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ý nó. 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.

Đường dẫn phải khớp với giai đoạn của tác vụ. Ví dụ, DELETE trên /prototype/:id với ID của một tác vụ build sẽ trả về 404.

Request

DELETE
/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -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ụ Fidget Pixel nào với ID này thuộc về tài khoản của bạn, hoặc giai đoạn của tác vụ không khớp với đường dẫn. Hãy kiểm tra lại ID, và sử dụng /prototype hoặc /build để khớp với tác vụ.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Truyền trực tiếp cập nhật tác vụ Fidget Pixel

Truyền trực tiếp các cập nhật của tác vụ Fidget Pixel dưới dạng Server-Sent Events (SSE). Đường dẫn phải khớp với giai đoạn của tác vụ. Nếu không khớp, ví dụ như ID của một tác vụ build được đặt tại /prototype/:id/stream, luồng sẽ gửi một sự kiện error duy nhất với status_code: 404 rồi đóng lại. Một id không phải là ID tác vụ hợp lệ cũng sẽ xảy ra tương tự nhưng với status_code: 400.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream
curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

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

Giá trị trả về

Một luồng các đối tượng tác vụ prototype hoặc build. Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, giống như Lấy một tác vụ Fidget Pixel 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 duy nhất thay thế, với status_code mà một yêu cầu get sẽ trả về.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

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

Trả về các tác vụ Fidget Pixel của bạn thuộc một giai đoạn, mỗi lần một trang. Đường dẫn xác định giai đoạn. /prototype chỉ trả về các tác vụ prototype, và /build chỉ trả về các tác vụ build.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

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

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Tham số đường dẫn

  • Name
    stage
    Type
    path
    Bắt buộc
    Description

    Giai đoạn cần liệt kê, prototype hoặc build.

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ụ prototype hoặc đối tượng tác vụ build, tương ứng với giai đoạn trong đường dẫn.

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

Một tác vụ prototype biến một bức ảnh thành hình ảnh pixel-art. Để biến hình ảnh đó thành các mảnh ghép có thể in 3D, hãy truyền ID của tác vụ vào build endpoint dưới dạng input_task_id.

Thuộc tính

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}
  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

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

  • 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ùng, có kết quả
    • FAILED: trạng thái cuối cùng, với lý do nằm trong task_error
    • CANCELED: trạng thái cuối cùng, 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. Giá trị là null cho đến khi đó.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm tác vụ đạt đến trạng thái cuối cùng, tính bằng mili giây Unix. Giá trị 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. Đó 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 Doanh nghiệp, 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. Giá trị 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. Giá trị là null trừ khi status là FAILED. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng bị tính cho tác vụ, sau khi hoàn lại (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ị là 0, vì Meshy sẽ hoàn lại tín dụng đó. Việc hủy chỉ hoàn lại tín dụng của 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
    image_urls
    Type
    array of strings
    Description

    URL tải xuống cho hình ảnh pixel-art. Mảng này có một URL sau khi tác vụ thành công, và trống cho đến khi đó.

    Các URL này đã được ký, vì vậy hãy lấy chúng mà không cần header Authorization. Chúng vẫn có hiệu lực cho đến expires_at. Việc lấy lại tác vụ trước thời điểm đó sẽ trả về cùng các URL, chứ không phải các URL được ký mới. Một URL đã hết hạn không thể được làm mới, vì vậy hãy tải xuống và lưu trữ các tệp trước thời điểm đó.

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

Một tác vụ build tạo ra các mảnh có thể in 3D từ một tác vụ prototype đã thành công. Meshy lấy mẫu hình ảnh pixel art lên lưới và trả về các mảnh trong một tệp 3MF đa màu duy nhất.

Thuộc tính

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?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-pixel-build.

  • Name
    name
    Type
    string
    Description

    name 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, với 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ị 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. Đó 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 các tài khoản Enterprise, vốn lưu giữ kết quả API vô thời hạn, thời điểm đó 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 cho tác vụ, sau khi đã hoàn lại (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ị là 0, vì Meshy sẽ hoàn lại tín dụng cho tác vụ đó. Việc hủy chỉ hoàn lại tín dụng 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 kết quả, được đánh khóa theo định dạng tệp. Đối tượng này có một mục, cho output.format bạn đã gửi, và rỗng cho đến khi tác vụ thành công.

    Các URL này đã được ký, vì vậy hãy lấy chúng mà không cần header Authorization. Chúng vẫn còn hiệu lực cho đến expires_at. Lấy lại tác vụ trước thời điểm đó sẽ trả về cùng các URL, chứ không phải URL được ký mới. Một URL đã hết hạn không thể được làm mới, vì vậy hãy tải xuống và lưu trữ các tệp trước thời điểm đó.

    • Name
      3mf
      Type
      string
      Description

      URL tải xuống cho tệp 3MF đa màu. Mỗi mảnh có phần thân màu xám và phần đỉnh mang màu của pixel tương ứng. Có mặt khi output.format là 3mf, giá trị mặc định.

Ví dụ đầu cuối

Các đoạn script cURL và Python sau đây chạy toàn bộ luồng. Mỗi script tạo một tác vụ prototype từ một bức ảnh và chờ nó hoàn tất. Sau đó, nó tạo một tác vụ build, chờ tác vụ đó, và tải xuống tệp 3MF từ model_urls.3mf.

Script cURL cần curl và jq, còn script Python cần gói requests. Để chạy một script, hãy làm theo các bước sau:

  1. Đặt MESHY_API_KEY thành khóa API của bạn.
  2. Đặt IMAGE_PATH thành đường dẫn của một ảnh cục bộ, hoặc IMAGE_URL thành một URL ảnh công khai.
  3. Tùy chọn: Để pixel hóa một đối tượng khác không phải người, hãy đặt PIXEL_TYPE thành other.
  4. Chạy script.

Một tác vụ prototype thường hoàn tất trong vòng vài phút. Một tác vụ build thường hoàn tất trong chưa đến một phút.

Trong ứng dụng của bạn, hãy hiển thị hình ảnh từ image_urls cho người dùng của bạn trước khi bạn tạo tác vụ build. Nếu họ không thích, hãy tạo một tác vụ prototype khác thay vào đó. Bằng cách này, bạn chỉ tiêu tốn tín dụng build cho một hình ảnh mà họ đã chấp thuận.

Complete flow

POST
/openapi/creative-lab/fidget-pixel/v1
#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"