Creative Lab — API đèn

Biến một prompt văn bản hoặc một ảnh nguồn thành chụp đèn có thể in 3D trong hai giai đoạn: nguyên mẫu tạo ra một ảnh ý tưởng màu trắng mờ được cách điệu, sau đó xây dựng biến ảnh ý tưởng đó thành một chụp đèn STL rỗng (tùy chọn ghép với một đĩa đế cho bộ gá nguồn sáng). Hai giai đoạn được liên kết 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 đèn

Tạo một ảnh ý tưởng màu trắng mờ duy nhất cho chụp đèn — hoặc từ một prompt văn bản (text-to-3D) hoặc từ ảnh tham chiếu (image-to-3D). ID tác vụ được trả về là giá trị bạn truyền làm input_task_id cho endpoint build. Tham khảo Đối tượng tác vụ nguyên mẫu đèn để biết cấu trúc phản hồi.

Tham số

Bắt buộc phải có đúng một trong hai trường text hoặc image_url. Truyền cả hai, hoặc không truyền trường nào, sẽ trả về 400.

Name
text
Type
string
Bắt buộc
Description
Prompt văn bản mô tả chủ thể chụp đèn mong muốn. Bắt buộc khi bỏ qua image_url. Tối đa 800 ký tự.

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 chụp đèn. Bắt buộc khi bỏ qua text. 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 hình ảnh:
- URL có thể truy cập công khai: URL có thể truy cập từ internet công cộng.
- Data URI: Data URI của hình ảnh được mã hóa base64. Ví dụ về Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
image_subject
Type
string
mặc định character
Description
Gợi ý danh mục chủ thể cho luồng image-to-3D. Các giá trị khả dụng:
- character (mặc định) — chủ thể là một nhân vật / đối tượng đơn lẻ (tượng nhỏ, độ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ị, rừng, v.v.).
Bị bỏ qua trên luồng text-to-3D.
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ự.

Trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ nguyên mẫu đèn vừa được tạo. Thăm dò endpoint Lấy tác vụ hoặc đăng ký stream cho đến khi tác vụ đạt SUCCEEDED, sau đó truyền ID đó đến endpoint build làm input_task_id.

Các trường hợp 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ố: Bắt buộc phải có đúng một trong hai trường text hoặc image_url.
- Cung cấp cả hai: Truyền cả text và image_url sẽ bị từ chối — chúng loại trừ lẫn nhau.
- Đị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 ngoài phạm vi: Hình ả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 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 NSFW hoặc sở hữu trí tuệ.
- Văn bản quá dài: text vượt quá 800 ký tự.
- image_subject không hợp lệ: Không phải một trong 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 độ của mình.

Request

POST

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

# Stage 1 (image-to-3D): generate a matte-white lampshade concept image
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"
  }'

# Stage 1 (text-to-3D): generate from a text prompt
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 '{
    "text": "a stylized owl perched on a tree branch under moonlight"
  }'

Response

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

Prototype example

Start with a source photo, then generate the prototype image used by the lamp build stage.

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

Tạo tác vụ dựng đèn

Tạo chụp đèn cuối cùng có thể in 3D từ một tác vụ nguyên mẫu đã thành công. Quá trình dựng chạy pipeline từ hình ảnh sang 3D trên hình ảnh ý tưởng của nguyên mẫu, sau đó hậu xử lý lưới thông qua bộ xử lý đèn để làm rỗng nó, làm phẳng phần trên, tùy chọn cắt một đế, và (khi chọn preset bộ gá) xuất một đĩa đế riêng cho nguồn sáng. Tham khảo Đối tượng tác vụ dựng đèn để xem cấu trúc 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 thông qua cùng endpoint OpenAPI này. Nguyên mẫu phải được tạo bằng cùng khóa API, phải đã đạt SUCCEEDED, và phải tạo ra đúng một hình ảnh ứng viên.
Các tác vụ nguyên mẫu được tạo thông qua webapp không được chấp nhận — endpoint dựng chỉ chấp nhận các tác vụ nguyên mẫu được tạo bởi POST /openapi/creative-lab/lamp/v1/prototype và từ chối mọi nguồn khác với 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ố tinh chỉnh tùy chọn cho hình học của chụp đè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 80
Description
Kích thước tối đa mục tiêu của hộp bao chụp đèn, tính bằng milimét. Lưới (mesh) được co giãn đồng đều để vừa khít. Phạm vi: [50, 400].
Name
thickness_mm
Type
number
mặc định 1.5
Description
Độ dày thành của chụp đèn rỗng, tính bằng milimét. Phạm vi: (0, 10].
Name
cut_amount_percent
Type
number
mặc định 35
Description
Tỷ lệ phần trăm chiều cao chụp đèn cần làm phẳng ở phía trên để bản in có thể đặt trên bàn in. Phạm vi: [1, 100].
Name
light_source_preset
Type
string
mặc định bambu_mh001_60mm
Description
Preset bộ gá nguồn sáng xác định có xuất (và xuất loại) đĩa đế cùng với chụp đèn hay không. Các giá trị khả dụng:
- bambu_mh001_60mm (mặc định) — xuất một đĩa đế 60 mm có kích thước phù hợp với bộ gá nguồn sáng tương thích. Kết quả bao gồm model_urls.base_stl.
- none — không có bộ gá, không có đĩa đế. model_urls.base_stl bị bỏ qua.
Name
fixture_offset_x_mm
Type
number
mặc định 0
Description
Độ lệch trục X theo chiều ngang của phần khoét bộ gá so với tâm chụp đè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 theo chiều dọc của phần khoét bộ gá so với đáy chụp đèn, tính bằng milimét. 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 lưới đã nhập trước khi xử lý, tính bằng độ. 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, bao gồm result.json của bộ xử lý đèn (chứa các chỉ số lưới đã đo + bộ tùy chọn đã được phân giải) 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 dựng. Các giá trị khả dụng:
- stl (mặc định) — trả về chụp đèn dưới dạng model_urls.lamp_stl, cộng thêm model_urls.base_stl khi light_source_preset ≠ none.
- zip — đóng gói mọi artifact mà bộ xử lý xuất 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 model_urls.bundle_zip.

Trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ dựng đèn mới được tạo. Thăm dò endpoint Lấy một tác vụ hoặc đăng ký stream cho đến khi tác vụ đạt 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à 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 SUCCEEDED.
- Không có ứng viên: Tác vụ nguyên mẫu đã thành công nhưng không tạo ra hình ảnh ứng viên nào.
- Tùy chọn 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 cho phép.
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ề người dùng khác, hoặc được tạo thông qua webapp (chỉ các tác vụ nguyên mẫu ở mode API mới có thể nối chuỗi vào quá trình dựng).
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.

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

The build task turns the selected prototype image into a printable lampshade model.

Creative Lab Lamp build model preview — Build model preview

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

Truy xuất một tác vụ đèn

Truy xuất một tác vụ nguyên mẫu hoặc bản dựng 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ụ bản dựng đượ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ụ nguyên mẫu đèn và Đối tượng tác vụ bản dựng đèn để biết cấu trúc phản hồi.

Tham số

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

Trả về

Phản hồi chứa đối tượng tác vụ đèn. Cấu trúc 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": 6,
  "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": 30,
  "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, tín dụng đã tiêu thụ 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 (worker có thể đã đang tiêu tốn Tài nguyên). Các tác vụ đã đạt đến trạng thái kết thúc (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
Mã định danh duy nhất của tác vụ đèn cần hủy.

Trả về

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

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

Name
400 - Bad Request
Description
Tác vụ đã ở trạng thái kết thúc 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 tác vụ 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 phát một tác vụ đèn

Truyền phát các cập nhật theo thời gian thực cho một tác vụ đèn qua SSE. Đường dẫn URL phải khớp với giai đoạn của tác vụ — việc 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.

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ đèn cần truyền phát.

Trả về

Trả về một stream gồm các đối tượng tác vụ Nguyên mẫu đèn hoặc Bản dựng đèn dưới dạng SSE. Đối với các tác vụ PENDING hoặc IN_PROGRESS, stream 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": 30,
  "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)

Liệt kê tác vụ đèn

Truy xuất danh sách có 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 chọn giai đoạn — /prototype trả về các tác vụ prototype; /build trả về các tác vụ build. Các tác vụ từ giai đoạn khác không được bao gồm trong bất kỳ phản hồi nào.

Tham số đường dẫn

Name
stage
Type
path
Bắt buộc
Description
Hoặc 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 lấy /prototype sẽ không bao giờ trả về tác vụ build và ngược lại.

Tham số truy vấn

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 được phép là 50 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.

Trả về

Trả về danh sách có phân trang của đối tượng tác vụ theo từng giai đoạn — hoặc đối tượng tác vụ prototype đèn khi liệt kê /prototype hoặc đối tượng tác vụ build đè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": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Đối tượng Tác vụ Nguyên mẫu đèn

Đố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 một hình ảnh ý tưởng màu trắng nhám, được cách điệu từ một prompt văn bản hoặc một ảnh nguồn. Đầu ra của giai đoạn này được nối tiếp vào giai đoạn xây dựng 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 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 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 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress của tác vụ. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian của thời điểm 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 12:00:00 PM GMT được biểu thị là 1693569600000. Điều này áp dụng cho tất cả dấu thời gian trong Meshy API.
Name
started_at
Type
timestamp
Description
Dấu thời gian của thời điểm 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 của thời điểm tác vụ được hoàn tất, tính bằng mili giây. Nếu tác vụ chưa được hoàn tất, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian của thời điểm 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 nếu 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 đối tượng task_error đầy đủ.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tiêu thụ bởi tác vụ này. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).
Name
image_urls
Type
array of strings
Description
Các URL có thể tải xuống cho các phương án hình ảnh ý tưởng được tạo bởi tác vụ nguyên mẫu này. Hiện tại API luôn trả về đúng một phương án; trường này là một mảng để các bản sửa đổi trong tương lai có thể hiển thị nhiều phương án mà không tạo 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": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

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

Đối tượng tác vụ xây dựng đèn là một đơn vị công việc mà Meshy theo dõi để tạo chụp đèn cuối cùng có thể in 3D từ một tác vụ nguyên mẫu SUCCEEDED. Quy trình xây dựng chạy pipeline bản nháp image-to-3D + texture trên ảnh ý tưởng của nguyên mẫu, sau đó hậu xử lý lưới thông qua bộ xử lý đèn để làm rỗng, làm phẳng và (tùy chọn) cắt một đế cố định.

Properties

Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ.
Name
type
Type
string
Description
Loại của tác vụ. Giá trị là creative-lab-lamp-build.
Name
name
Type
string
Description
Tên tác vụ được cung cấp khi tác vụ được tạo. Chuỗi rỗng nếu không có tên nào được cung cấp.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được bắt đầu, tính bằng mili giây.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được 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ả 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. Chỉ có ý nghĩa khi trạng thái là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tiêu thụ bởi tác vụ này. Trả về 0 cho 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 các tạo phẩm đã tạo, được lập chỉ mục theo tên tạo phẩm. Tập hợp 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 chụp đèn lamp.stl. Có mặt khi output.format là stl (mặc định).
- Name
  base_stl
  Type
  string
  Description
  URL có thể tải xuống cho đế cố định base.stl. Có mặt khi output.format là stl và options.light_source_preset không phải là none. Bị bỏ qua khi preset bộ cố định là none.
- Name
  bundle_zip
  Type
  string
  Description
  URL có thể tải xuống cho gói zip chứa mọi tạo phẩm mà bộ xử lý phát ra (lamp.stl, tùy chọn base.stl, 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": 30,
  "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=***"
  }
}