Creative Lab — API đèn

Biến một bức ảnh nguồn thành chao đèn có thể in 3D qua hai giai đoạn: prototype tạo ra một hình ảnh khái niệm màu trắng mờ theo phong cách cách điệu và biến nó thành một mô hình 3D rỗng (GLB), sau đó build chạy bộ xử lý đèn trên mô hình đó để tạo ra các bộ phận STL có thể in — một chao đèn hở đáy với một tấm đế cho đui đèn nguồn sáng, 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ụ nguyên mẫu Lamp

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

Name
image_subject
Type
string
mặc định character
Description
Gợi ý về 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 / vật thể đơn lẻ (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 non, cảnh 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, hình ảnh nguyên mẫu được trả về dưới dạng PNG RGBA trong suốt với nền đã được xóa, để bạn có thể ghép chủ thể lên bất kỳ nền nào.

Giá trị trả về

Thuộc tính result của phản hồi chứa id của tác vụ nguyên mẫu lamp vừa được tạo. Hãy 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ế độ 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ố: image_url là bắt buộc.
- Định dạng hình ả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 hình ảnh nằm ngoài phạm vi cho phép: Hình ảnh quá nhỏ, vượt quá kích thước tệp tối đa, hoặc vượt quá số điểm ảnh tối đa.
- URL không thể truy cập: Không thể tải xuống image_url (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ờ: Hình ảnh đầu vào đã bị gắn cờ bởi moderation nội dung không phù hợp (NSFW) hoặc quyền 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ụ nguyên mẫu

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

Ảnh mèo nguồn được 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 ra từ ảnh nguồn — Đầu ra nguyên mẫ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 cuối cùng từ một task nguyên mẫu (prototype) đã 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 fixture preset đượ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 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 task 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 task nguyên mẫu được tạo qua webapp sẽ không được chấp nhận — endpoint build chỉ chấp nhận các task 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 task tùy chọn dùng cho mục đích hiển thị. Tối đa 100 ký tự.

`options`

Các tham số tùy 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 mô hình bị cắt phẳng ở phía dưới, để chao đèn có thể đặt 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 xác định cách phần đáy được xây dựng. 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 đều 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 sẽ 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
Góc xoay quanh trục X được á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
Góc xoay quanh trục Y được á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
Góc xoay quanh trục Z được á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 là true và output.format là zip, sẽ bao gồm tệp 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 fixture preset được thiết lập), cộng thêm model_urls.base_stl khi light_source_preset ≠ none.
- zip — đóng gói tất cả các artifact mà bộ xử lý tạo ra (lamp.stl, base.stl tùy chọn, result.json tùy chọn) vào một tệp zip duy nhất và trả về dưới dạng model_urls.bundle_zip.

Giá trị trả về

Thuộc tính result của phản hồi chứa id của task lamp build vừa được tạo. Thăm dò endpoint Get a Task hoặc đăng ký stream cho đến khi task đạt trạng thái SUCCEEDED, sau đó tải 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ệ.
- Task cha chưa thành công: Task nguyên mẫu được tham chiếu chưa đạt trạng thái SUCCEEDED.
- Không có mô hình: Task 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 hợ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 task này.
Name
404 - Not Found
Description
Task nguyên mẫu được tham chiếu không tồn tại, thuộc về người dùng khác, hoặc được tạo qua webapp (chỉ các task 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"
}

Ví dụ build

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

Xem trước mô hình build đèn Creative Lab — Xem trước mô hình build

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

Truy xuất Tác vụ đèn

Truy xuất 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ụ — 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 đèn và Đối tượng Tác vụ Build đèn để biết hình dạng phản hồi.

Tham số

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

Giá trị trả về

Phản hồi chứa đối tượng tác vụ đèn. Hình dạng 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 PENDING, các tín dụng tiêu thụ khi tạo sẽ được hoàn lại. Các tác vụ đã IN_PROGRESS sẽ bị hủy mà không hoàn lại (công nhân có thể đã đang tiêu tốn tài nguyên). Các tác vụ đã đạt trạng thái cuối (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ụ — DELETE trên /prototype/:buildId trả về 404.

Tham số Đường dẫn

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

Trả về

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

Các chế độ lỗi

Name
400 - Bad Request
Description
Tác vụ đã ở trạng thái cuối 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.

Yêu cầu

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

Phản hồi

// Returns 204 No Content on success (empty body).

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

Truyền trực tuyến một tác vụ đèn

Truyền trực tuyến các cập nhật theo thời gian thực cho một tác vụ đèn 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 luồng tại /prototype/:buildId/stream sẽ phát ra một event: error payload duy nhất với status_code: 404 và đóng luồng đó.

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất cho tác vụ đèn cần truyền trực tuyến.

Giá trị trả về

Trả về một luồng các đối tượng tác vụ Lamp Prototype hoặc Lamp Build dưới dạng Server-Sent Events. Đối với các tác vụ PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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)

Danh sách tác vụ Lamp

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ụ tạo mẫu thử; /build trả về các tác vụ dựng. Các tác vụ thuộc giai đoạn còn lại sẽ không được đưa vào bất kỳ phản hồi nào.

Tham số đường dẫn

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

Tham số truy vấn

Name
page_num
Type
integer
mặc định 1
Description
Số trang cho việc 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à 50 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.

Giá trị trả về

Trả về danh sách phân trang các đối tượng tác vụ theo từng giai đoạn — hoặc đối tượng tác vụ tạo 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 Tác vụ Nguyên mẫu đèn (Lamp Prototype Task)

Đối tượng Tác vụ Nguyên mẫu đèn 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) màu trắng mờ cách điệu 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 dựng hình thông qua input_task_id.

Thuộc tính

Name
id
Type
string
Description
Mã đị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 UUID) cho id tác vụ như là 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 của 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. 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 số PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress 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 thị 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ả của 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ố lượng 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 đượ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 dựng hình sẽ xử lý.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống cho bản xem trước đã đượ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 bởi tác vụ nguyên mẫu 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ươ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 chao đèn 3D có thể in được cuối cùng 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ấm đế và giá gắn cố định (fixture mount).

Thuộc tính

Name
id
Type
string
Description
Đị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
Tiến trình 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 hoàn tất, 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 các 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 tài liệu tham khảo đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã bị tiêu hao 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 các artifact được tạo ra, được đánh khóa theo tên artifact. 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 của lamp.stl: chao đèn hở đáy cùng với tấm đế mang lỗ gắn cố định, hoặc một chao đèn kín duy nhất khi options.light_source_preset là none. Xuất hiện khi output.format là stl (giá trị mặc định).
- Name
  base_stl
  Type
  string
  Description
  URL có thể tải xuống của base.stl, giá gắn cố định nguồn sáng. Xuất hiện 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 của một gói zip chứa mọi artifact 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). Xuất hiện khi output.format là zip. Khi bundle_zip xuất hiện, 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=***"
  }
}