Creative Lab — Fidget Pixel API

Biến một ảnh nguồn thành một tấm bảng fidget nghệ thuật pixel đa màu có thể in 3D qua hai giai đoạn: prototype chuyển ảnh của bạn thành ảnh nghệ thuật pixel, sau đó build lấy mẫu ảnh đó lên lưới 16×16 hoặc 32×32 và biến mỗi pixel thành một mảnh ghép hình vuông hoặc hình lục giác khớp với nhau, được xuất ra dưới dạng một tệp 3MF duy nhất trong đó các đối tượng mang theo màu sắc của chúng để một phần mềm cắt lớp đa sợi in mỗi mảnh với đúng màu. Hai giai đoạn được liên kết với nhau thông qua 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 đăng ký trả phí. Các yêu cầu từ tài khoản gói miễn phí sẽ bị từ chối với lỗi 402 Payment Required.

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

Create a Fidget Pixel Prototype Task

Tạo một hình ảnh pixel-art duy nhất từ ảnh nguồn. ID tác vụ được trả về chính là giá trị bạn sẽ truyền dưới dạng input_task_id cho endpoint build. Hãy gọi lại endpoint này để nhận một kết quả khác nếu kết quả hiện tại chưa như mong muốn — mỗi lần gọi sẽ được tính phí riêng. Tham khảo The Fidget Pixel Prototype Task Object để biết cấu trúc phản hồi.

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Ảnh nguồn để Meshy chuyển thành pixel. Chúng tôi hiện hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Định dạng được xác định bằng cách giải mã dữ liệu ảnh, không dựa vào phần mở rộng tệp của URL — một URL không có phần mở rộng, hoặc một URL có chuyển hướng, vẫn hoạt động miễn là các byte giải mã ra một định dạng được hỗ trợ. Các chuyển hướng HTTP sẽ được đi theo.
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 cộng.
- Data URI: Một data URI của ảnh được mã hóa base64. Ví dụ về data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
type
Type
string
Bắt buộc
Description
Nội dung mà ảnh thể hiện. Lựa chọn này quyết định phong cách pixel hóa, vì vậy hãy chọn cẩn thận — hai kiểu này cho ra kết quả khác nhau rõ rệt. Các giá trị khả dụng:
- person — chủ thể là một người (chân dung hoặc toàn thân). Tạo ra một sprite pixel phong cách chibi của chủ thể.
- other — bất kỳ thứ gì khác: thú cưng, đồ vật, linh vật, logo, phong cảnh. Tạo ra một biểu tượng pixel phong cách bead-art của chủ thể.
Name
name
Type
string
Description
Tên tác vụ tùy chọn để hiển thị. Tối đa 100 ký tự.

Kết quả trả về

Thuộc tính result của phản hồi chứa id của tác vụ tạo nguyên mẫu fidget pixel 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 đó truyền ID đó vào 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 hợp lệ. Các nguyên nhân phổ biến:
- Thiếu tham số: cả image_url và type đều bắt buộc.
- Type không hợp lệ: type phải là person hoặc other.
- Đị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 nằm ngoài phạm vi cho phép: Ảnh quá nhỏ, vượt quá dung lượng 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 (lỗi 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ờ: Ảnh đầu vào bị gắn cờ 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
Không đủ tín dụng để thực hiện tác vụ này, hoặc khóa API thuộc về một tài khoản gói miễn phí.
Name
403 - Forbidden
Description
Ảnh đầu vào bị gắn cờ bởi moderation về sở hữu trí tuệ (Content flagged for intellectual property violation). Chỉ các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ mới bị chặn; không có khoản phí nào được tính.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.
Name
500 - Internal Server Error
Description
Bản thân việc kiểm tra sở hữu trí tuệ không thể hoàn tất (Unable to perform intellectual property check, please try again). Các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ sẽ bị chặn khi kiểm tra này thất bại; không có khoản phí nào được tính — hãy thử lại yêu cầu.

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

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

Tạo tác vụ Build Fidget Pixel

Tạo các mảnh ghép có thể in 3D từ một tác vụ prototype đã thành công. Quá trình build lấy mẫu hình ảnh pixel-art của prototype vào lưới được yêu cầu, lượng tử hóa nó thành tối đa color_count màu, và tạo ra một mảnh ghép lồng vào nhau cho mỗi ô lưới. Sản phẩm đầu ra là một tệp 3MF duy nhất, trong đó mỗi mảnh ghép là một đối tượng riêng biệt được gắn thẻ theo màu của nó, sẵn sàng cho phần mềm cắt lớp đa sợi (multi-filament slicer). Tham khảo Đối tượng Tác vụ Build Fidget Pixel để biết cấu trúc phản hồi.

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
Task ID của một tác vụ prototype được tạo qua cùng endpoint OpenAPI này. Prototype phải được tạo bởi cùng một tài khoản Meshy và phải đã đạt trạng thái SUCCEEDED.
Các tác vụ prototype được tạo qua webapp không được chấp nhận — endpoint build chỉ chấp nhận các tác vụ prototype được tạo ra bởi POST /openapi/creative-lab/fidget-pixel/v1/prototype và từ chối bất kỳ nguồn nào khác với mã lỗi 404.
Name
name
Type
string
Description
Tên tác vụ tùy chọn dùng để hiển thị. Tối đa 100 ký tự.

`options`

Hình học mảnh ghép tùy chọn. Mỗi trường đều có giá trị mặc định — chỉ gửi những trường bạn muốn ghi đè. Đây là các tùy chọn tương tự mà webapp Creative Lab cung cấp; chiều cao chốt, tỷ lệ nắp, và các cấu hình sản xuất khác được suy ra từ shape và piece_size_mm và không được công khai.

Name
shape
Type
string
mặc định square
Description
Hình dạng mặt cắt của mỗi mảnh ghép. Các giá trị khả dụng:
- square (mặc định) — mảnh ghép hình vuông trên lưới vuông.
- hex — mảnh ghép hình lục giác trên lưới lục giác. Mảnh ghép hex chỉ khả dụng ở kích thước 6 và 8 mm.
Name
grid_size
Type
integer
mặc định 32
Description
Số lượng mảnh ghép dọc theo mỗi cạnh của bảng. Các giá trị khả dụng: 16 hoặc 32. Lưới 32 giữ lại nhiều chi tiết hơn; lưới 16 nghĩa là ít mảnh ghép hơn nhưng lớn hơn cho cùng một chủ thể.
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. Các giá trị khả dụng: 6, 8, hoặc 10. Cùng với grid_size, giá trị này quyết định kích thước bảng in — ví dụ 32 × 8 mm ≈ 26 cm mỗi cạnh. 10 không khả dụng cho shape: "hex" (mặt hex nghiêng gây hiện tượng đùn thừa (overhang) trên hầu hết máy in FDM 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 mà hình ảnh được lượng tử hóa thành. Phạm vi: [1, 8]. Mỗi màu tương ứng với một sợi filament trong phần mềm cắt lớp của bạn.
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. Phạm vi: [10, 80].

`output`

Bộ chọn định dạng dữ liệu đầu ra tùy chọn. Mặc định là 3mf, hiện là giá trị duy nhất được hỗ trợ.

Name
format
Type
string
mặc định 3mf
Description
Sản phẩm được trả về bởi quá trình build. Các giá trị khả dụng:
- 3mf (mặc định) — trả về một tệp model.3mf duy nhất tại model_urls.3mf, với mỗi đối tượng tương ứng một mảnh ghép và màu của mảnh ghép được gắn kèm với mỗi đối tượng.

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ụ build fidget pixel vừa được tạo. Hãy thăm dò (poll) endpoint Lấy một Tác vụ hoặc đăng ký luồng dữ liệu (stream) cho đến khi tác vụ đạt trạng thái SUCCEEDED, sau đó tải sản phẩm về từ model_urls.3mf.

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

Name
400 - Bad Request
Description
Yêu cầu không hợp lệ. Các nguyên nhân phổ biến:
- Thiếu tham số: input_task_id là bắt buộc.
- UUID không hợp lệ: input_task_id không phải là một UUID hợp lệ.
- Tác vụ gốc chưa hoàn tất: Tác vụ prototype được tham chiếu chưa đạt trạng thái SUCCEEDED.
- Không có ứng viên: Tác vụ prototype đã thành công nhưng không tạo ra hình ảnh pixel-art nào; hãy tạo một prototype mới.
- Tùy chọn nằm ngoài phạm vi: Một trong các trường của options nằm ngoài tập hợp hoặc phạm vi cho phép — ví dụ options.grid_size must be 16 or 32, hoặc options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
- Định dạng không được hỗ trợ: output.format phải là 3mf.
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, hoặc khóa API thuộc về một tài khoản gói miễn phí.
Name
403 - Forbidden
Description
Hình ảnh của prototype được tham chiếu đã bị đánh dấu bởi hệ thống moderation sở hữu trí tuệ. Chỉ các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ mới bị chặn; không có khoản phí nào bị trừ.
Name
404 - Not Found
Description
Tác vụ prototype được tham chiếu không tồn tại, thuộc về một người dùng khác, hoặc được tạo qua webapp (chỉ các tác vụ prototype ở chế độ API mới có thể được nối tiếp vào build).
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.
Name
500 - Internal Server Error
Description
Không thể xác định kết luận về sở hữu trí tuệ của prototype được tham chiếu (Unable to perform intellectual property check, please try again). Các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ sẽ mặc định thất bại (fail closed) đối với kiểm tra này; không có khoản phí nào bị trừ — hãy thử lại yêu cầu.

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

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

Lấy thông tin một tác vụ Fidget Pixel

Lấy thông tin một tác vụ prototype hoặc build với id tác vụ hợp lệ. Đường dẫn URL phải khớp với giai đoạn của tác vụ — nếu một tác vụ build được lấy thông qua /prototype/:id sẽ trả về 404, và ngược lại.

Tham khảo Đối tượng tác vụ Prototype Fidget Pixel và Đối tượng tác vụ Build Fidget Pixel để biết cấu trúc phản hồi.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ fidget pixel cần lấy thông tin.

Giá trị trả về

Phản hồi chứa đối tượng tác vụ fidget pixel. Cấu trúc phụ thuộc vào giai đoạn nào được yêu cầu.

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

Name
400 - Bad Request
Description
id không phải là một UUID hợp lệ (Invalid ID).
Name
403 - Forbidden
Description
Hình ảnh của tác vụ đã bị đánh dấu bởi hệ thống kiểm duyệt sở hữu trí tuệ. Chỉ các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ mới bị chặn.
Name
404 - Not Found
Description
Tác vụ không tồn tại, thuộc về một người dùng khác, hoặc giai đoạn của tác vụ không khớp với đường dẫn URL.
Name
500 - Internal Server Error
Description
Không thể hoàn tất việc kiểm tra sở hữu trí tuệ (Unable to perform intellectual property check, please try again); các tài khoản Enterprise có bật tính năng lọc sở hữu trí tuệ sẽ mặc định thất bại (fail closed). Hãy thử lại yêu cầu.

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

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. Nếu tác vụ vẫn đang ở trạng thái PENDING, số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại. Các tác vụ đã ở trạng thái IN_PROGRESS sẽ bị hủy nhưng không được hoàn tiền (worker có thể đã đang 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.

Đường dẫn URL phải khớp với giai đoạn của tác vụ — thực hiện DELETE trên /prototype/:buildId sẽ trả về 404.

Tham số đường dẫn

Name
id
Type
path
Description
Định danh duy nhất của tác vụ fidget pixel cần hủy.

Giá trị trả về

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

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không hợp lệ. Các nguyên nhân phổ biến:
- ID không hợp lệ: id không phải là một UUID hợp lệ.
- Trạng thái cuối cùng: Tác vụ đã ở trạng thái SUCCEEDED, FAILED hoặc CANCELED và không thể bị hủy.
Name
404 - Not Found
Description
Tác vụ không tồn tại, thuộc về một người dùng khác, hoặc giai đoạn của nó không khớp với đường dẫn URL.

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

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

Stream tác vụ Fidget Pixel

Truyền trực tuyến các cập nhật theo thời gian thực cho một tác vụ fidget pixel thông qua Server-Sent Events (SSE). Đường dẫn URL phải khớp với giai đoạn của tác vụ — mở một stream tại /prototype/:buildId/stream sẽ phát ra một event: error payload duy nhất với status_code: 404 và đóng stream; một id không hợp lệ cũng sẽ hành xử tương tự với status_code: 400 (Invalid ID).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ fidget pixel cần truyền trực tuyến.

Giá trị trả về

Trả về một stream các đối tượng tác vụ Fidget Pixel Prototype hoặc Fidget Pixel Build dưới dạng Server-Sent Events. Mỗi khung dữ liệu mang toàn bộ đối tượng tác vụ cho giai đoạn đó — cùng cấu trúc mà endpoint Get trả về — vì vậy trong 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 giá trị (null, [] hoặc {}) và finished_at là null.

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

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

List Fidget Pixel Tasks

Lấy danh sách phân trang các tác vụ fidget pixel của bạn cho một giai đoạn duy nhất. Đường dẫn URL sẽ chọn giai đoạn — /prototype trả về các tác vụ prototype; /build trả về các tác vụ build. Các tác vụ thuộc giai đoạn còn lại sẽ không được bao gồm trong cả hai phản hồi.

Path Parameters

Name
stage
Type
path
Bắt buộc
Description
Là prototype hoặc build. Bộ sưu tập chỉ trả về các tác vụ có giai đoạn khớp với URL — việc gọi /prototype sẽ không bao giờ trả về các tác vụ build và ngược lại.

Query Parameters

Name
page_num
Type
integer
mặc định 1
Description
Số trang dùng 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 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.

Returns

Trả về danh sách phân trang của đối tượng tác vụ theo từng giai đoạn — hoặc đối tượng tác vụ prototype fidget pixel khi liệt kê /prototype hoặc đối tượng tác vụ build fidget pixel khi liệt kê /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=***"
    ]
  }
]

The Fidget Pixel Prototype Task Object

The Fidget Pixel Prototype Task object là một đơn vị công việc mà Meshy theo dõi để pixel hóa một ảnh nguồn thành hình ảnh dạng pixel-art. Đầu ra của giai đoạn này được nối tiếp vào giai đoạn build thông qua input_task_id.

Thuộc tính

Name
id
Type
string
Description
Đị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 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-pixel-prototype.
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ể là một trong các giá trị 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.
Một dấu thời gian biểu diễn số mili-giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, tuân theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023, 12:00:00 CH GMT được biểu diễn dưới dạng 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ụ 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ụ kết thúc, tính bằng mili-giây. Nếu tác vụ chưa kết thúc, thuộc tính này sẽ là null.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả tác vụ hết hạn, tính bằng mili-giây — 3 ngày sau khi tác vụ kết thúc. Các tài khoản Enterprise giữ kết quả API vô thời hạn (xem Lưu giữ tài nguyên); đối với họ, dấu thời gian này được đặt cách khoảng 100 năm.
Name
preceding_tasks
Type
integer
Description
Số lượng các 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. Một tác vụ đạt đến trạng thái SUCCEEDED sẽ bị tính phí đầy đủ cho giai đoạn của nó. Một tác vụ không bao giờ được tạo (một lỗi 4xx tại thời điểm yêu cầu, bao gồm cả việc bị từ chối bởi moderation) sẽ không bị tính phí. Một tác vụ đạt đến trạng thái FAILED trả về 0 — khoản phí sẽ được hoàn lại. Việc hủy thông qua DELETE chỉ hoàn tiền khi tác vụ vẫn đang ở trạng thái PENDING; một tác vụ đã ở trạng thái IN_PROGRESS vẫn bị tính phí, vì công việc đã được thực hiện.
Name
image_urls
Type
array of strings
Description
Các URL có thể tải xuống cho hình ảnh dạng pixel-art được tạo bởi tác vụ prototype này. Hiện tại API luôn trả về chính xác một hình ảnh; trường này là một mảng để các phiên bản trong tương lai có thể hiển thị nhiều ứng viên mà không gây ra thay đổi phá vỡ tương thích. Rỗng cho đến khi tác vụ đạt đến trạng thái SUCCEEDED.
Đây là các URL đã được ký: 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, tức là 3 ngày sau finished_at, và việc đọc lại tác vụ trong khoảng thời gian đó sẽ trả về cùng một URL thay vì một URL vừa được ký mới. Hãy tự tải xuống và lưu trữ các tệp trước thời điểm đó — không có cách nào để làm mới một liên kết đã hết hạn.

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

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

Đối tượng Tác vụ Build Fidget Pixel là một đơn vị công việc mà Meshy theo dõi để tạo ra các mảnh ghép có thể in từ một tác vụ nguyên mẫu đã thành công. Bản build lấy mẫu hình ảnh pixel-art của nguyên mẫu lên lưới yêu cầu và xuất bản một tệp 3MF duy nhất được gắn thẻ màu.

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho tác vụ.
Name
type
Type
string
Description
Loại của tác vụ. Giá trị là creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
Tên tác vụ được cung cấp khi tác vụ được tạo. 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ể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress của tác vụ. Nếu tác vụ chưa được 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.
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. null cho đến khi tác vụ bắt đầu.
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. null cho đến khi tác vụ hoàn thành.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả tác vụ hết hạn, tính bằng mili giây — 3 ngày sau khi tác vụ hoàn thành. Các tài khoản Doanh nghiệp lưu giữ kết quả API vô thời hạn (xem Lưu giữ tài nguyên); đối với họ, dấu thời gian này được đặt khoảng 100 năm sau.
Name
preceding_tasks
Type
integer
Description
Số lượng các tác vụ đứng trước. Chỉ có ý nghĩa khi trạng thái 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 tham chiếu đầy đủ về đố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. Một tác vụ đạt đến SUCCEEDED sẽ bị tính toàn bộ chi phí cho giai đoạn của nó. Một tác vụ không bao giờ được tạo ra (một lỗi 4xx tại thời điểm yêu cầu, bao gồm cả việc từ chối do moderation) sẽ không bị tính phí. Một tác vụ đạt đến FAILED trả về 0 — khoản phí được hoàn lại. Việc hủy qua DELETE chỉ hoàn tiền khi tác vụ vẫn đang PENDING; một tác vụ đã ở trạng thái IN_PROGRESS vẫn bị tính phí, vì công việc đã được thực hiện.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho tài nguyên đã tạo, được đánh khóa theo định dạng. Chứa chính xác một mục — định dạng được yêu cầu qua output.format của yêu cầu build. Trống cho đến khi tác vụ đạt đến SUCCEEDED.
Đây là các URL đã ký: tải chúng mà không có header Authorization. Chúng vẫn hợp lệ cho đến expires_at, tức là 3 ngày sau finished_at, và việc đọc lại tác vụ trong khoảng thời gian đó sẽ trả về cùng một URL thay vì một URL được ký mới. Hãy tự tải xuống và lưu trữ các tệp trước thời điểm đó — không có cách nào để làm mới một liên kết đã hết hạn.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống cho tệp 3MF. Một đối tượng cho mỗi mảnh, mỗi mảnh được gắn thẻ với màu bảng màu của nó, để phần mềm cắt lớp đa sợi in gán sợi in theo từng màu. Hiện diện khi output.format là 3mf (giá trị mặc đị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=***"
  }
}

Ví dụ đầy đủ (End-to-End)

Luồng hoàn chỉnh: tạo một prototype từ một ảnh, thăm dò (poll) nó cho đến khi SUCCEEDED, tạo một build từ đó, thăm dò build cho đến khi SUCCEEDED, sau đó tải xuống 3MF từ model_urls.

Một prototype thường hoàn thành trong vòng vài phút; một build thường hoàn thành trong chưa đầy một phút. Trong một tích hợp thực tế, bạn nên hiển thị mục image_urls của prototype cho người dùng cuối và để họ xác nhận (hoặc chạy lại prototype) trước khi tiêu tốn tín dụng cho build.

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"