API Nam châm tủ lạnh của Creative Lab

Biến một bức ảnh thành nam châm tủ lạnh có thể in 3D với phần phù điêu có màu và mặt sau phẳng, qua hai giai đoạn. Tác vụ prototype tạo ra một hình ảnh khái niệm có màu từ bức ảnh. Tác vụ build biến hình ảnh đó thành mô hình 3D phù điêu, và lấy ID của tác vụ prototype làm input_task_id.

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

Tạo tác vụ prototype Fridge Magnet

Tạo ra một hình ảnh khái niệm (concept image) có màu từ một bức ảnh. Để xây dựng mô hình 3D, hãy truyền ID của tác vụ này vào 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ụ prototype Fridge Magnet.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/prototype

# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/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>"
  }'

Response

{
  "result": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}

Ví dụ prototype

Bắt đầu với một ảnh nguồn, sau đó tạo hình ảnh prototype được sử dụng bởi giai đoạn build fridge magnet.

Ảnh phong cảnh nguồn được sử dụng làm đầu vào cho Creative Lab Fridge Magnet — Đầu vào prototype

Đầu ra prototype Creative Lab Fridge Magnet được tạo từ ảnh nguồn — Đầu ra prototype

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Bức ảnh cần chuyển thành hình ảnh khái niệm nam châm tủ lạnh, 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>).
Ảnh phải là file JPG, JPEG, PNG, hoặc WebP có dung lượng tối đa 20 MB.
Name
name
Type
string
Description
Tên cho 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ụ. Tên dài hơn sẽ trả về 400.
Name
remove_background
Type
boolean
mặc định false
Description
Có xóa nền khỏi hình ảnh prototype hay không. true sẽ trả về một ảnh PNG RGBA trong suốt giữ nguyên toàn bộ nam châm, để bạn có thể đặt nó trên bất kỳ nền nào. Quá trình build cũng sẽ bắt đầu từ hình ảnh đã xóa nền. Nếu Meshy không thể xóa nền, nó sẽ trả về ảnh kèm nền, và tác vụ vẫn thành công.
Tùy chọn remove_background của build là riêng biệt.

Giá trị trả về

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

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

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Ví dụ:
- Thiếu image_url.
- Ảnh không phải là file JPG, JPEG, PNG, hoặc WebP.
- Ảnh quá nhỏ, vượt quá 20 MB, hoặc vượt quá số pixel tối đa.
- Meshy không thể tải ảnh xuống, 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ệ.
- Ảnh bị gắn cờ 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
Thiếu khóa API hoặc khóa API 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 đủ 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 IP Filtering, và Meshy đã gắn cờ hình ảnh vì vi phạm 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 tới:
- Bạn đã gửi nhiều yêu cầu hơn 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 độ.
- Có quá nhiều tác vụ của bạn đang xếp hàng 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 đã hết tín dụng, bạn đã đạt tới 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 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/fridge-magnet/v1/build

Tạo tác vụ build nam châm tủ lạnh

Tạo mô hình nam châm tủ lạnh có thể in 3D từ một tác vụ prototype đã thành công. Meshy biến hình ảnh khái niệm của prototype thành một phù điêu bản đồ độ sâu (depth-map relief), và trả về một file mô hình theo định dạng bạn chọn. Để biết các trường của tác vụ, xem The Fridge Magnet build task object.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "options": {
      "badge_shape": "rounded-rect",
      "size_mm": 60,
      "relief_height_mm": 3.3
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

Build example

The build task turns the selected prototype image into a 3D-printable fridge magnet model.

Creative Lab Fridge Magnet build model preview — Build model preview

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
ID của tác vụ prototype cần build. ID này 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/fridge-magnet/v1/prototype, với trạng thái SUCCEEDED.
Một ID không phải là tác vụ prototype nam châm tủ lạnh của bạn từ API sẽ trả về 404, kể cả prototype đượ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ự. Tên này 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ác cài đặt tùy chọn cho hình dạng của phù điêu. 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. Một giá trị nằm ngoài phạm vi của trường sẽ trả về 400.

Name
badge_shape
Type
string
mặc định rounded-rect
Description
Đường viền của nam châm khi Meshy không truy vết nó từ chủ thể. Meshy dùng trường này khi remove_background là false, hoặc khi nó không thể tìm thấy đường viền của chủ thể.
Các giá trị khả dụng:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
mặc định 60
Description
Độ dài cạnh của hình vuông bao quanh nam châm, tính bằng milimet, tối đa 400. 0 sẽ dùng giá trị mặc định.
Name
relief_height_mm
Type
number
mặc định 3.3
Description
Chiều cao tối đa của phù điêu so với đế, tính bằng milimet, từ 0 đến 20.
Name
relief_offset_mm
Type
number
mặc định 0
Description
Hạ phù điêu xuống bao nhiêu, tính bằng milimet, từ 0 đến 20. Meshy trừ giá trị này khỏi chiều cao của phù điêu ở mọi vị trí, xuống tới đế.
Name
base_thickness_mm
Type
number
mặc định 2.0
Description
Độ dày của tấm đế phẳng phía sau phù điêu, tính bằng milimet, từ 0 đến 20. Đế mặc định 2 mm cho nam châm đủ độ dày để bám vào tủ lạnh, nhờ đó phù điêu không có cảm giác mỏng manh.
Name
has_closed_back
Type
boolean
mặc định true
Description
Có đóng kín mặt sau của nam châm hay không, mặt mà bạn dán nam châm vào. false sẽ để mặt sau hở, như một lớp vỏ rỗng.
Name
relief_curve
Type
string
mặc định linear
Description
Đường cong ánh xạ giá trị bản đồ độ sâu thành chiều cao phù điêu.
Các giá trị khả dụng:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
mặc định 1.0
Description
Cường độ của đường cong, tối đa 10. Các đường cong gamma và s-curve sử dụng tham số này, còn linear thì bỏ qua. 0 sẽ dùng giá trị mặc định.
Name
invert_depth
Type
boolean
mặc định false
Description
Có đảo ngược bản đồ độ sâu hay không, để các vùng tối hơn trở thành phù điêu cao hơn.
Name
smoothing
Type
number
mặc định 0.24
Description
Mức độ làm mịn bản đồ độ sâu trước khi Meshy xây dựng phù điêu, từ 0 đến 10.
Name
relief_scale
Type
number
mặc định 1.0
Description
Mức độ phóng to phù điêu và texture của nó bên trong đường viền, quanh tâm, tối đa 10. Giá trị trên 1 sẽ phóng to chủ thể, và giá trị dưới 1 sẽ thu nhỏ chủ thể. Nó không làm thay đổi chiều cao của phù điêu. 0 sẽ dùng giá trị mặc định.
Name
depth_threshold
Type
number
mặc định 0.1
Description
Giá trị bản đồ độ sâu mà dưới mức đó Meshy sẽ đặt độ sâu về 0, từ 0 đến 1.
Name
remove_background
Type
boolean
mặc định true
Description
Có truy vết đường viền nam châm từ chủ thể hay không, để nam châm theo đúng hình dạng của chủ thể. false sẽ dùng đường viền badge_shape thay thế. Meshy cũng dùng badge_shape khi nó không thể tìm thấy đường viền của chủ thể.
Tham số này tách biệt với tham số remove_background của prototype, vốn thiết lập liệu hình ảnh prototype có nền trong suốt hay không.
Name
export_resolution
Type
integer
mặc định 512
Description
Độ phân giải lưới của mô hình được xuất, từ 64 đến 512. Meshy xây dựng hình học từ một bản đồ độ sâu 512 pixel, vì vậy một lưới mịn hơn sẽ chỉ thêm các mặt mà không thêm chi tiết. 0 sẽ dùng giá trị mặc định.

`output`

Tùy chọn. Thiết lập định dạng file mà build trả về.

Name
format
Type
string
mặc định glb
Description
Định dạng file mà build trả về.
Các giá trị khả dụng:
- glb: một file model.glb, trong model_urls.glb
- obj: một file zip chứa model.obj, model.mtl, và texture.png, trong model_urls.obj
- zip: một file zip chứa mọi file mà Meshy tạo ra, trong model_urls.bundle_zip

Giá trị trả về

Trường result chứa ID của tác vụ build mới. Lấy tác vụ hoặc theo dõi luồng của nó cho đến khi status là SUCCEEDED. Sau đó tải file xuống từ mục nhập duy nhất trong model_urls.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy được. Ví dụ:
- input_task_id bị thiếu hoặc không phải là ID tác vụ hợp lệ.
- Trạng thái của tác vụ prototype không phải là SUCCEEDED. Nếu nó vẫn đang chạy, hãy chờ rồi thử lại. Nếu nó thất bại hoặc bị hủy, hãy tạo một tác vụ prototype mới.
- Tác vụ prototype đã thành công nhưng không có hình ảnh. Hãy tạo một tác vụ prototype mới.
- Một trường trong options nằm ngoài phạm vi hoặc không phải là giá trị khả dụng.
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 những 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 giới hạn tín dụng.
- Tài khoản đang dùng gói miễn phí.
Hãy kiểm tra số tín dụng và gói của bạn, sau đó thử lại.
Name
404 - Not Found
Description
input_task_id không khớp với bất kỳ tác vụ prototype nam châm tủ lạnh nào do tài khoản của bạn tạo bằng API. Một prototype được tạo trong ứng dụng web cũng sẽ trả về 404. Hãy gửi ID result từ một phản hồi tạo prototype.
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. Hãy chờ vài giây rồi thử lại. Xem Rate limits.
- Có quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Hãy chờ một số tác vụ hoàn tất rồi thử lại.
- Trên gói không giới hạn mà 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 chờ một tác vụ hoàn tất, hoặc nạp thêm tín dụng.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Lấy một tác vụ Fridge Magnet

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 qua /prototype/:id sẽ trả về 404, và một tác vụ prototype được yêu cầu qua /build/:id cũng vậy.

Để biết các trường, xem Đối tượng tác vụ prototype của Fridge Magnet và Đối tượng tác vụ build của Fridge Magnet.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?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 trường hợp 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ì sở hữu trí tuệ của bên thứ ba. Các tác vụ build và các nhóm dùng gói Enterprise 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ụ Fridge Magnet 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 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/fridge-magnet/v1/(prototype|build)/:id

Xóa một tác vụ nam châm tủ lạnh

Hủy một tác vụ nam châm tủ lạnh. Hủy một tác vụ PENDING sẽ hoàn lại tín dụng của nó. Một tác vụ IN_PROGRESS 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/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -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), do đó không thể bị hủy.
Name
404 - Not Found
Description
Không có tác vụ nam châm tủ lạnh 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/fridge-magnet/v1/(prototype|build)/:id/stream

Truyền trực tiếp tác vụ Fridge Magnet

Truyền trực tiếp các cập nhật của một tác vụ nam châm tủ lạnh 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 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.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/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; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?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 đối tượng tác vụ đầy đủ, giống như Lấy một tác vụ Fridge Magnet 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ế, với status_code mà một yêu cầu get sẽ trả về.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)

Liệt kê các tác vụ Fridge Magnet

Trả về các tác vụ nam châm tủ lạnh của bạn thuộc một giai đoạn, mỗi lần một trang. Đường dẫn sẽ chọn 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/fridge-magnet/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "type": "creative-lab-fridge-magnet-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729543210000,
    "started_at": 1729543215000,
    "finished_at": 1729543242000,
    "expires_at": 1729802442000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?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 sẽ trả về trang đầu tiên. Một giá trị nằm 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. Một giá trị nằm 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 task prototype Fridge Magnet

Một task prototype tạo ra một hình ảnh concept đã tô màu từ một bức ảnh. Để biến hình ảnh này thành mô hình 3D, hãy truyền ID của task vào build endpoint dưới dạng input_task_id.

Thuộc tính

Example Fridge Magnet Prototype Task Object

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
ID của task. Đừng dựa vào định dạng của nó.
Name
type
Type
string
Description
Loại task, luôn là creative-lab-fridge-magnet-prototype.
Name
name
Type
string
Description
name mà bạn đã gửi khi tạo task, hoặc "" nếu bạn không gửi.
Name
status
Type
string
Description
Trạng thái của task.
Các giá trị khả dụng:
- PENDING: đang chờ trong hàng đợi
- IN_PROGRESS: đang tạo kết quả
- SUCCEEDED: cuối cùng, có kết quả
- FAILED: cuối cùng, với lý do trong task_error
- CANCELED: 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. Nó là 0 cho đến khi task bắt đầu và 100 khi nó thành công.
Name
created_at
Type
timestamp
Description
Thời điểm task đượ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 task, tính bằng mili-giây Unix. Là null cho đến khi đó.
Name
finished_at
Type
timestamp
Description
Thời điểm task đạt đến trạng thái cuối cùng, 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 task 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 task hoàn thành. Đối với các tài khoản Enterprise, vốn giữ kết quả API vô thời hạn, thì đó 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 task trong hàng đợi khi nó đang ở trạng thái PENDING. 1 nghĩa là nó sẽ bắt đầu tiếp theo. Là 0 sau khi task 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 task thất bại. Là null trừ khi status là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng bị tính phí cho task, sau khi hoàn tiền (nếu có). Một request trả về lỗi sẽ không bị tính phí. Một task thất bại sẽ là 0, vì Meshy hoàn lại tín dụng cho nó. Việc hủy chỉ hoàn lại tín dụng cho task khi nó đ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 request danh sách sẽ trả về 500. Trong trường hợp đó, hãy thử lại request.
Name
image_urls
Type
array of strings
Description
URL tải xuống cho hình ảnh concept. Mảng này có một URL sau khi task thành công, và rỗng cho đến khi đó.

Đối tượng tác vụ build Fridge Magnet

Một tác vụ build tạo ra nam châm tủ lạnh 3D từ một tác vụ prototype đã thành công. Nó trả về một tệp mô hình ở định dạng bạn đã yêu cầu.

Thuộc tính

Example Fridge Magnet Build Task Object

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?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-fridge-magnet-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ị này là 0 cho đến khi tác vụ bắt đầu và 100 khi nó 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. 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. 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 các 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 nó đang ở trạng thái PENDING. 1 nghĩa là nó sẽ bắt đầu tiếp theo. 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. 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 sẽ có giá trị 0, vì Meshy sẽ hoàn lại tiền. Việc hủy chỉ hoàn tiền cho một tác vụ khi nó đ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 tệp mô hình, với một mục cho output.format bạn đã yêu cầu. {} cho đến khi tác vụ thành công.
- Name
  glb
  Type
  string
  Description
  URL tải xuống cho tệp GLB. Có mặt khi output.format là glb.
- Name
  obj
  Type
  string
  Description
  URL tải xuống cho một tệp zip chứa model.obj, model.mtl, và texture.png. Có mặt khi output.format là obj.
- Name
  bundle_zip
  Type
  string
  Description
  URL tải xuống cho một tệp zip chứa mọi tệp mà Meshy tạo ra. Có mặt khi output.format là zip.