Creative Lab — API Đèn

Chuyển đổi một bức ảnh nguồn thành chao đèn có thể in 3D qua hai giai đoạn: tạo mẫu tạo ra một hình ảnh khái niệm màu trắng mờ theo phong cách và chuyển nó thành một mô hình 3D rỗng (GLB), sau đó bản dựng chạy bộ xử lý đèn trên mô hình đó để tạo ra các bộ phận STL có thể in được — một chao đèn hở đáy với tấm đế cho đui đèn, cùng với giá đỡ đui đèn. Hai giai đoạn được liên kết thông qua input_task_id.

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

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

Tạo Tác vụ Prototype Đèn

Tạo một ảnh concept đơn sắc trắng mờ từ ảnh tham chiếu và chuyển đổi nó thành mô hình 3D chao đèn rỗng. Phản hồi mang theo cả ảnh concept (image_urls) và mô hình 3D (model_urls.glb cùng thumbnail_url). ID tác vụ được trả về chính là giá trị bạn truyền vào input_task_id cho endpoint build. Tham khảo Đối tượng Tác vụ Prototype Đèn để 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 mà Meshy sử dụng làm tham chiếu trực quan cho chao đèn. Hiện chúng tôi hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Có hai cách để cung cấp ảnh:
- URL truy cập công khai: Một URL có thể truy cập từ internet công khai.
- Data URI: Một data URI mã hóa base64 của ảnh. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu ảnh mã hóa base64 của bạn>.

Name
image_subject
Type
string
mặc định character
Description
Gợi ý danh mục chủ thể để chọn prompt stylization. Các giá trị khả dụng:
- character (mặc định) — chủ thể là nhân vật đơn lẻ / đối tượng (mô hình nhân vật, động vật, linh vật, v.v.).
- landscape — chủ thể là cảnh ngoài trời / toàn cảnh (núi, cảnh quan thành phố, rừng, v.v.).
Name
name
Type
string
Description
Tên tác vụ tùy chọn dùng cho mục đích hiển thị. Tối đa 100 ký tự.
Name
remove_background
Type
boolean
mặc định false
Description
Khi được đặt thành true, ảnh prototype sẽ được trả về dưới dạng PNG RGBA trong suốt với nền đã bị loại bỏ, giúp bạn có thể ghép chủ thể vào bất kỳ nền nào.

Kết quả trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ prototype đèn vừa được tạo. Poll endpoint Lấy một Tác vụ 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ế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- Thiếu tham số: image_url là bắt buộc.
- Đị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á kích thước 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 image_url xuống (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 hoặc sở hữu trí tuệ.
- image_subject không hợp lệ: Không phải là character / landscape.
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.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

Request

POST

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

# Stage 1: concept image + hollow 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ụ prototype

Bắt đầu với một ảnh nguồn; prototype trả về ảnh concept và một mô hình 3D rỗng mà giai đoạn build sẽ xử lý.

Source cat photo used as the Creative Lab Lamp input — Prototype input

Creative Lab Lamp prototype output generated from the source photo — Prototype output

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

Create a Lamp Build Task

Tạo ra các bộ phận có thể in 3D cuối cùng từ một tác vụ nguyên mẫu đã thành công. Quá trình build chạy bộ xử lý đèn trên mô hình 3D của nguyên mẫu: nó co giãn mô hình theo diameter_mm, làm phẳng phần đáy theo cut_amount_percent, khoét rỗng đến thickness_mm, mở phần đáy, và — khi một preset fixture được chọn — thêm một tấm đế có lỗ fixture và một giá đỡ riêng cho nguồn sáng. Tham khảo The Lamp Build Task Object để biết hình dạng của phản hồi.

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
ID tác vụ của một tác vụ nguyên mẫu được tạo qua cùng endpoint OpenAPI này. Nguyên mẫu phải được tạo bằng cùng một khóa API, phải đã đạt trạng thái SUCCEEDED, và phải đã tạo ra một mô hình 3D.
Các tác vụ nguyên mẫu được tạo qua webapp không được chấp nhận — endpoint build chỉ chấp nhận các tác vụ nguyên mẫu được tạo ra bởi POST /openapi/creative-lab/lamp/v1/prototype và từ chối bất kỳ nguồn nào khác với mã 404.
Name
name
Type
string
Description
Tên tác vụ tùy chọn cho mục đích hiển thị. Tối đa 100 ký tự.

`options`

Các tham số điều chỉnh tùy chọn cho hình học của chao đèn. Mỗi trường đều có giá trị mặc định hợp lý — chỉ gửi những trường bạn muốn ghi đè.

Name
diameter_mm
Type
number
mặc định 150
Description
Kích thước tối đa mục tiêu của hộp bao chao đèn, tính bằng milimét. Lưới được co giãn đồng đều để vừa khít. Phạm vi: [50, 400].
Name
thickness_mm
Type
number
mặc định 1
Description
Độ dày thành của chao đèn rỗng, tính bằng milimét. Phạm vi: (0, 10].
Name
cut_amount_percent
Type
number
mặc định 1
Description
Phần trăm chiều cao của mô hình bị cắt phẳng ở đáy, để chao đèn nằm vừa trên bàn in và có một lỗ mở cho fixture. Phạm vi: [1, 100].
Name
light_source_preset
Type
string
mặc định bambu_mh001_60mm
Description
Preset fixture nguồn sáng quyết định cách xây dựng phần đáy. Các giá trị khả dụng:
- bambu_mh001_60mm (mặc định) — chao đèn hở đáy cùng với một tấm đế mang lỗ fixture 60 mm, cả hai nằm trong model_urls.lamp_stl, và giá đỡ fixture nằm trong model_urls.base_stl.
- none — một chao đèn kín duy nhất trong model_urls.lamp_stl; model_urls.base_stl bị bỏ qua.
Name
fixture_offset_x_mm
Type
number
mặc định 0
Description
Độ lệch trục X của lỗ fixture trên tấm đế, tương đối so với tâm chao đèn, tính bằng milimét. Chỉ có ý nghĩa khi light_source_preset ≠ none. Phạm vi: [-80, 80].
Name
fixture_offset_z_mm
Type
number
mặc định 0
Description
Độ lệch trục Z (chiều sâu) của lỗ fixture trên tấm đế, tương đối so với tâm chao đèn, tính bằng milimét. Chỉ có ý nghĩa khi light_source_preset ≠ none. Phạm vi: [-80, 80].
Name
rotate_x_deg
Type
number
mặc định 0
Description
Phép xoay quanh trục X áp dụng cho mô hình trước khi xử lý, tính bằng độ. Ba phép xoay được áp dụng dưới dạng góc Euler XYZ quanh tâm của mô hình. Phạm vi: [-360, 360].
Name
rotate_y_deg
Type
number
mặc định 0
Description
Phép xoay quanh trục Y áp dụng cho lưới đã nhập trước khi xử lý, tính bằng độ. Phạm vi: [-360, 360].
Name
rotate_z_deg
Type
number
mặc định 0
Description
Phép xoay quanh trục Z áp dụng cho lưới đã nhập trước khi xử lý, tính bằng độ. Phạm vi: [-360, 360].
Name
include_result_json
Type
boolean
mặc định false
Description
Khi true và output.format là zip, bao gồm result.json của bộ xử lý đèn (tên pipeline, cảnh báo, và đường dẫn artifact) bên trong gói. Bị bỏ qua khi output.format là stl.

`output`

Bộ chọn định dạng truyền tải tùy chọn. Mặc định là stl.

Name
format
Type
string
mặc định stl
Description
Gói artifact được trả về bởi quá trình build. Các giá trị khả dụng:
- stl (mặc định) — trả về model_urls.lamp_stl (chao đèn, cùng với tấm đế khi một preset fixture được thiết lập), cộng thêm model_urls.base_stl khi light_source_preset ≠ none.
- zip — đóng gói mọi artifact mà bộ xử lý tạo ra (lamp.stl, base.stl tùy chọn, result.json tùy chọn) thành một file zip duy nhất và trả về dưới dạng model_urls.bundle_zip.

Kết quả 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 đèn vừa được tạo. Hãy thăm dò endpoint Get a Task hoặc đăng ký stream cho đến khi tác vụ đạt trạng thái SUCCEEDED, sau đó tải xuống các artifact từ model_urls.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. 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ụ cha chưa thành công: Tác vụ nguyên mẫu được tham chiếu chưa đạt trạng thái SUCCEEDED.
- Không có mô hình: Tác vụ nguyên mẫu đã thành công nhưng không tạo ra mô hình 3D nào.
- Options nằm ngoài phạm vi: Một trong các trường options nằm ngoài phạm vi cho phép hoặc tập enum của nó.
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.
Name
404 - Not Found
Description
Tác vụ nguyên mẫu đượ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ụ nguyên mẫu ở chế độ API mới có thể nối tiếp vào build).
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

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ụ build biến mô hình 3D của nguyên mẫu thành các bộ phận chao đèn có thể in được.

Creative Lab Lamp build model preview — Build model preview

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

Truy xuất một Lamp Task

Truy xuất một prototype task hoặc build task với id task hợp lệ. Đường dẫn URL phải khớp với giai đoạn của task — một build task được truy xuất qua /prototype/:id sẽ trả về 404, và ngược lại.

Tham khảo The Lamp Prototype Task Object và The Lamp Build Task Object để biết hình dạng phản hồi.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của lamp task cần truy xuất.

Giá trị trả về

Phản hồi chứa đối tượng lamp task. Hình dạng của nó phụ thuộc vào giai đoạn được yêu cầu.

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

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

Xóa một tác vụ đèn

Hủy một tác vụ đèn. 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 mà không được hoàn tín dụng (vì worker có thể đã bắt đầu 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ụ — gọi DELETE trên /prototype/:buildId sẽ trả về 404.

Tham số đường dẫn (Path Parameters)

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

Kết quả trả về

Trả về 204 No Content khi thành công với nội dung phản hồi trống.

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

Name
400 - Bad Request
Description
Tác vụ đã ở trạng thái cuối cùng và không thể bị hủy.
Name
404 - Not Found
Description
Tác vụ không tồn tại, thuộc về 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/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).

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

Truyền trực tiếp một Lamp Task

Truyền các cập nhật theo thời gian thực cho một lamp task thông qua Server-Sent Events (SSE). Đường dẫn URL phải khớp với giai đoạn của task — mở một stream tại /prototype/:buildId/stream sẽ phát ra một payload event: error duy nhất với status_code: 404 và đóng stream lại.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của lamp task cần truyền trực tiếp.

Giá trị trả về

Trả về một stream các đối tượng task Lamp Prototype hoặc Lamp Build dưới dạng Server-Sent Events. Mỗi khung dữ liệu mang theo toàn bộ đối tượng task cho giai đoạn đó — cùng cấu trúc mà endpoint Get trả về — vì vậy trong khi task đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra chỉ đơn giản là chưa được điền dữ liệu (null, [] hoặc {}) và finished_at là null.

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 PENDING frame below is abbreviated 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=***"
  }
}

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

List Lamp Tasks

Lấy danh sách phân trang các tác vụ đèn của bạn cho một giai đoạn duy nhất. Đường dẫn URL xác định giai đoạn — /prototype trả về các tác vụ mẫu thử; /build trả về các tác vụ dựng. Các tác vụ từ giai đoạn còn lại không được bao gồm trong bất kỳ phản hồi nào.

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 truy vấn /prototype sẽ không bao giờ trả về các tác vụ dựng và ngược lại.

Query Parameters

Name
page_num
Type
integer
mặc định 1
Description
Số trang 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 để sắp xếp theo. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự 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ụ mẫu thử đèn khi liệt kê /prototype hoặc đối tượng tác vụ dựng đèn khi liệt kê /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=***"
    ]
  }
]

Đối tượng Lamp Prototype Task

Đối tượng Lamp Prototype Task là một đơn vị công việc mà Meshy theo dõi để tạo ra một hình ảnh khái niệm (concept image) cách điệu màu trắng mờ từ một ảnh nguồn và chuyển đổi nó thành một mô hình 3D rỗng. Đầ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) cho id tác vụ như một chi tiết triển khai, 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 tác vụ. Giá trị là creative-lab-lamp-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 trình 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.
Dấu thời gian thể hiện số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, theo tiêu chuẩn RFC 3339. Ví dụ: Thứ Sáu, ngày 1 tháng 9 năm 2023 lúc 12:00:00 CH GMT được biểu diễn là 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ụ được bắt đầu, tính bằng mili giây. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0.
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. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
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.
Name
preceding_tasks
Type
integer
Description
Số lượng 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 tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng đã tiêu thụ bởi tác vụ này. Xuất hiện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các tác vụ FAILED (tín dụng sẽ được hoàn lại khi thất bại).
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho mô hình 3D được tạo ra từ hình ảnh khái niệm. Xuất hiện khi tác vụ đã thành công; là {} trước đó.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống cho mô hình chao đèn rỗng màu trắng mờ ở định dạng GLB. Đây là mô hình mà giai đoạn build sẽ xử lý.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống cho bản xem trước đã kết xuất của mô hình 3D. Là chuỗi rỗng cho đến khi tác vụ thành công.
Name
image_urls
Type
array of strings
Description
Các URL có thể tải xuống cho các ứng viên hình ảnh khái niệm được tạo ra bởi tác vụ prototype này. Hiện tại API luôn trả về chính xác một ứng viên; 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ính tương thích.

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

Đối tượng Lamp Build Task

Đối tượng Lamp Build Task là một đơn vị công việc mà Meshy theo dõi để tạo ra mô hình chao đèn 3D có thể in được từ một prototype task đã thành công. Quá trình build chạy bộ xử lý đèn trên mô hình 3D của prototype để khoét rỗng nó, làm phẳng và mở phần đáy, và (với một fixture preset) thêm đế đặt và giá đỡ fixture.

Thuộc tính

Name
id
Type
string
Description
Mã định danh duy nhất cho task.
Name
type
Type
string
Description
Loại của task. Giá trị là creative-lab-lamp-build.
Name
name
Type
string
Description
Tên task được cung cấp khi task đượ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 task. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress của task. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0. Khi task đã 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 task được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
dấu thời gian khi task được bắt đầu, tính bằng mili giây.
Name
finished_at
Type
timestamp
Description
dấu thời gian khi task được hoàn thành, tính bằng mili giây.
Name
expires_at
Type
timestamp
Description
dấu thời gian khi kết quả của task hết hạn, tính bằng mili giây.
Name
preceding_tasks
Type
integer
Description
Số lượng task đứng trước. Chỉ có ý nghĩa khi status là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các task 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ố tín dụng đã tiêu thụ bởi task này. Trả về 0 đối với các task FAILED (tín dụng sẽ được hoàn lại khi thất bại).
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho những tài nguyên được tạo ra, được đánh khóa theo tên tài nguyên. Tập hợp các khóa phụ thuộc vào output.format và options.light_source_preset:
- Name
  lamp_stl
  Type
  string
  Description
  URL có thể tải xuống cho lamp.stl: chao đèn hở đáy cùng với đế đặt mang lỗ fixture, hoặc một chao đèn kín duy nhất khi options.light_source_preset là none. Có mặt khi output.format là stl (giá trị mặc định).
- Name
  base_stl
  Type
  string
  Description
  URL có thể tải xuống cho base.stl, giá đỡ fixture nguồn sáng. Có mặt khi output.format là stl và options.light_source_preset không phải là none. Bị bỏ qua khi fixture preset là none.
- Name
  bundle_zip
  Type
  string
  Description
  URL có thể tải xuống cho một gói zip chứa mọi tài nguyên mà bộ xử lý tạo ra (lamp.stl, base.stl tùy chọn, và — khi options.include_result_json là true — result.json). Có mặt khi output.format là zip. Khi bundle_zip có mặt, lamp_stl / base_stl sẽ bị bỏ qua.

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