Creative Lab Lamp API

Biến một bức ảnh thành một chụp đèn (lampshade) có thể in 3D qua hai giai đoạn. Một tác vụ prototype tạo ra một hình ảnh concept màu trắng mờ (matte-white) và biến nó thành một mô hình 3D. Một tác vụ build, lấy ID của tác vụ prototype làm input_task_id, biến mô hình đó thành các bộ phận STL có thể in được. Với preset fixture mặc định, các bộ phận là một chụp đèn hở đáy với một tấm đế cho bộ đèn chiếu sáng, và giá gắn bộ đèn.

POST /openapi/creative-lab/lamp/v1/prototype
POST /openapi/creative-lab/lamp/v1/build

POST/openapi/creative-lab/lamp/v1/prototype

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

Tạo một hình ảnh khái niệm màu trắng mờ từ một bức ảnh và chuyển nó thành một mô hình chụp đèn 3D. Tác vụ trả về hình ảnh khái niệm trong image_urls, và mô hình trong model_urls.glb với bản xem trước trong thumbnail_url. Để tạo các bộ phận có thể in, hãy truyền ID của tác vụ này tới build endpoint 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 Lamp.

Request

POST

/openapi/creative-lab/lamp/v1/prototype

# Stage 1: concept image + 3D lampshade model from a source photo
curl https://api.meshy.ai/openapi/creative-lab/lamp/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>",
    "image_subject": "character"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Ví dụ nguyên mẫu

Bắt đầu với một bức ảnh nguồn. Nguyên mẫu trả về hình ảnh khái niệm và mô hình 3D mà giai đoạn build xử lý.

Ảnh mèo nguồn được sử dụng làm đầu vào cho Creative Lab Lamp — Đầu vào nguyên mẫu

Đầu ra nguyên mẫu Creative Lab Lamp được tạo từ bức ảnh nguồn — Đầu ra nguyên mẫu

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Bức ảnh dùng làm cơ sở cho chụp đèn, dưới dạng một URL công khai hoặc một 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ó dung lượng tối đa 20 MB.

Name
image_subject
Type
string
mặc định character
Description
Loại chủ thể trong bức ảnh, quyết định cách Meshy cách điệu hóa nó.
Các giá trị khả dụng:
- character: một nhân vật hoặc đối tượng đơn lẻ, chẳng hạn như một mô hình thu nhỏ, một con vật, hoặc một linh vật
- landscape: một cảnh ngoài trời hoặc toàn cảnh, chẳng hạn như một ngọn núi, một cảnh quan thành phố, hoặc một khu rừng
Name
name
Type
string
Description
Tên cho tác vụ, tối đa 100 ký tự. Tên này đượ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 nguyên mẫu hay không. true trả về một PNG RGBA trong suốt, để bạn có thể đặt chủ thể lên bất kỳ nền nào. Meshy cũng xây dựng mô hình 3D từ hình ảnh mà không có nền của nó. Nếu Meshy không thể xóa nền, nó sẽ sử dụng hình ảnh với nền của nó, và tác vụ vẫn thành công.

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 truyền tác vụ qua luồng cho đến khi status là SUCCEEDED. Sau đó truyền ID tới build endpoint dưới dạng input_task_id.

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à tệp JPG, JPEG, PNG, hoặc WebP.
- Hình ảnh quá nhỏ, trên 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ị gắn cờ là NSFW.
- image_subject không phải là character hay landscape.
Thông báo lỗi cho biết vấn đề nào đã được phát hiện. Khắc phục 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ệ. 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 của mình.
- Tài khoản đang ở 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 Lọc IP, và Meshy đã gắn cờ hình ảnh vì 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. Chờ 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 hoặc đang chạy. Chờ một số tác vụ hoàn thành, sau đó thử lại.
- Trên một 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. Chờ một tác vụ hoàn thành, hoặc 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.

POST/openapi/creative-lab/lamp/v1/build

Create a Lamp build task

Tạo ra các bộ phận có thể in 3D từ một tác vụ nguyên mẫu đã thành công. Meshy co giãn mô hình của nguyên mẫu theo diameter_mm, cắt phẳng phần đáy theo cut_amount_percent, và khoét rỗng theo thickness_mm. Với một bản thiết lập sẵn phụ kiện, nó cũng mở phần đáy, thêm một tấm đế có lỗ phụ kiện, và tạo một giá đỡ riêng cho đèn. Để biết các trường của tác vụ, xem Đối tượng tác vụ xây dựng Lamp.

Request

POST

/openapi/creative-lab/lamp/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

Tác vụ xây dựng chuyển đổi mô hình 3D của nguyên mẫu thành các bộ phận chụp đèn có thể in được.

Creative Lab Lamp 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ụ nguyên mẫu cần xây dựng. 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/lamp/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 Lamp của bạn từ API sẽ trả về 404, bao gồm cả 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ự. 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.

`options`

Các cài đặt tùy chọn cho hình dạng của chụp đèn. Mỗi trường đều có giá trị mặc định, vì vậy chỉ cần gửi những trường bạn muốn thay đổi.

Name
diameter_mm
Type
number
mặc định 150
Description
Kích thước lớn nhất của chụp đèn, tính bằng milimét, từ 50 đến 400. Meshy co giãn mô hình một cách đồng đều để vừa khít. 0 sẽ dùng giá trị mặc định, và bất kỳ giá trị nào khác nằm ngoài phạm vi sẽ trả về 400.
Name
thickness_mm
Type
number
mặc định 1
Description
Độ dày thành của chụp đèn, tính bằng milimét, tối đa 10. 0 sẽ dùng giá trị mặc định, và giá trị âm hoặc giá trị lớn hơn 10 sẽ trả về 400.
Name
cut_amount_percent
Type
number
mặc định 1
Description
Tỷ lệ phần trăm chiều cao của mô hình cần cắt phẳng ở đáy, từ 1 đến 100. Phần đáy phẳng giúp chụp đèn đặt được trên bàn in và chừa chỗ cho phụ kiện. Giá trị nằm ngoài phạm vi sẽ trả về 400.
Name
light_source_preset
Type
string
mặc định bambu_mh001_60mm
Description
Bản thiết lập sẵn cho phụ kiện đèn, quyết định cách Meshy xây dựng phần đáy.
Các giá trị khả dụng:
- bambu_mh001_60mm: một chụp đèn hở đáy với tấm đế có lỗ phụ kiện 60 mm, cả hai đều nằm trong model_urls.lamp_stl, và giá đỡ phụ kiện nằm trong model_urls.base_stl
- none: một chụp đèn kín đơn lẻ trong model_urls.lamp_stl, không có model_urls.base_stl
Name
fixture_offset_x_mm
Type
number
mặc định 0
Description
Khoảng cách dịch chuyển lỗ phụ kiện dọc theo trục X tính từ tâm của chụp đèn, tính bằng milimét, từ -80 đến 80. Chỉ áp dụng khi light_source_preset không phải none.
Name
fixture_offset_z_mm
Type
number
mặc định 0
Description
Khoảng cách dịch chuyển lỗ phụ kiện dọc theo trục Z (độ sâu) tính từ tâm của chụp đèn, tính bằng milimét, từ -80 đến 80. Chỉ áp dụng khi light_source_preset không phải none.
Name
rotate_x_deg
Type
number
mặc định 0
Description
Góc xoay quanh trục X áp dụng cho mô hình trước khi Meshy xử lý, tính bằng độ, từ -360 đến 360. Meshy áp dụng ba phép xoay dưới dạng góc Euler XYZ quanh tâm của mô hình.
Name
rotate_y_deg
Type
number
mặc định 0
Description
Góc xoay quanh trục Y áp dụng cho mô hình trước khi Meshy xử lý, tính bằng độ, từ -360 đến 360.
Name
rotate_z_deg
Type
number
mặc định 0
Description
Góc xoay quanh trục Z áp dụng cho mô hình trước khi Meshy xử lý, tính bằng độ, từ -360 đến 360.
Name
include_result_json
Type
boolean
mặc định false
Description
Có thêm tệp result.json vào gói zip hay không, chứa tên của pipeline đã chạy, các cảnh báo, và đường dẫn tệp. Yêu cầu output.format được đặt là zip. true với stl sẽ trả về 400.

`output`

Tùy chọn. Thiết lập các tệp mà quá trình xây dựng trả về.

Name
format
Type
string
mặc định stl
Description
Các tệp mà quá trình xây dựng trả về.
Các giá trị khả dụng:
- stl: model_urls.lamp_stl, chụp đèn cùng tấm đế khi có bản thiết lập sẵn phụ kiện, và model_urls.base_stl khi light_source_preset không phải none
- zip: một tệp zip trong model_urls.bundle_zip, với lamp.stl, và base.stl cùng result.json khi áp dụng

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 truyền trực tuyến nó cho đến khi status là SUCCEEDED. Sau đó tải các tệp xuống từ model_urls.

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

Name
400 - Bad Request
Description
Yêu cầu không thể thực thi. 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ó mô hình 3D. Hãy tạo một tác vụ nguyên mẫu mới.
- Một trường options nằm ngoài phạm vi cho phép hoặc không phải là một giá trị khả dụng.
- output.format không phải là stl hoặc zip, hoặc include_result_json là true mà không có zip.
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
404 - Not Found
Description
input_task_id không khớp với bất kỳ tác vụ nguyên mẫu Lamp nào do 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ừ mộ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 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, 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 chờ hoặc đang chạy. Hãy chờ một số tác vụ hoàn thành, sau đó thử lại.
- Trên một 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 chờ một tác vụ hoàn thành, hoặc nạp thêm tín dụng.

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

Lấy tác vụ Lamp

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, xem Đối tượng tác vụ prototype Lamp và Đối tượng tác vụ build Lamp.

Request

GET

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.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ụ 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.
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ụ prototype vì vi phạm 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ụ Lamp 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/lamp/v1/(prototype|build)/:id

Xóa một tác vụ Lamp

Hủy một tác vụ Lamp. 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ụ, gọi 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/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/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 trố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ụ Lamp 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/lamp/v1/(prototype|build)/:id/stream

Truyền trực tiếp (stream) một tác vụ đèn

Truyền trực tiếp các cập nhật của một tác vụ đèn 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 dùng 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/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?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ề

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ư những gì Lấy thông tin một tác vụ đèn 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/lamp/v1/(prototype|build)

Liệt kê các tác vụ Lamp

Trả về các tác vụ Lamp của bạn ở 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/lamp/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-lamp-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 30,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "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. 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 đèn (Lamp)

Một tác vụ prototype tạo ra một hình ảnh concept màu trắng mờ (matte-white) từ một bức ảnh và biến nó thành một mô hình 3D. Để tạo ra các bộ phận có thể in được, hãy truyền ID của tác vụ đó tới build endpoint dưới dạng input_task_id.

Thuộc tính

Example Lamp Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?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-lamp-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ó 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. Đó 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, 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 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 trừ đi mọi khoản hoàn lại. 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 phí cho nó. Việc hủy chỉ hoàn lại phí cho 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à 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
Các URL tải xuống cho mô hình 3D được tạo ra từ hình ảnh concept. {} cho đến khi tác vụ thành công.
- Name
  glb
  Type
  string
  Description
  URL tải xuống cho mô hình chao đèn, dưới dạng tệp GLB. Giai đoạn build sẽ biến mô hình này thành các bộ phận có thể in được.
Name
thumbnail_url
Type
string
Description
URL tải xuống cho một hình ảnh xem trước của mô hình 3D. "" cho đến khi tác vụ thành công.
Name
image_urls
Type
array of strings
Description
Các URL tải xuống cho hình ảnh concept. Mảng này có một URL sau khi tác vụ thành công, và trống cho đến khi đó.

Đối tượng tác vụ xây dựng Lamp

Tác vụ xây dựng chuyển đổi mô hình 3D của một tác vụ prototype đã thành công thành các bộ phận chao đèn có thể in được. Meshy làm rỗng mô hình và cắt phẳng đáy của nó. Với một preset đui đèn, tác vụ này còn mở đáy và thêm tấm đế cùng giá gắn đui đèn.

Thuộc tính

Example Lamp Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?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-lamp-build.
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: cuối cùng, kèm theo kết quả
- FAILED: cuối cùng, kèm theo 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. 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. Giá trị 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 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. Thời điểm 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, thời điểm 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à tác vụ sẽ bắt đầu kế tiếp. 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 phí cho tác vụ, sau khi trừ đi bất kỳ khoản hoàn trả nào. 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 trả tín dụng cho nó. Việc hủy chỉ hoàn trả tín dụng 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 các tệp có thể in được. Những khóa nào xuất hiện phụ thuộc vào output.format và options.light_source_preset.
- Name
  lamp_stl
  Type
  string
  Description
  URL tải xuống cho lamp.stl. Với một preset đui đèn, đây là chao đèn hở đáy cùng với tấm đế có lỗ đui đèn. Với options.light_source_preset được đặt là none, đây là một chao đèn kín đơn lẻ. Xuất hiện khi output.format là stl.
- Name
  base_stl
  Type
  string
  Description
  URL tải xuống cho base.stl, giá gắn cho đui đèn. Xuất hiện khi output.format là stl và options.light_source_preset không phải là none.
- Name
  bundle_zip
  Type
  string
  Description
  URL tải xuống cho một tệp zip chứa lamp.stl, cùng với base.stl và result.json khi chúng áp dụng được. Xuất hiện khi output.format là zip, và khi đó lamp_stl và base_stl sẽ bị bỏ qua.