API Tượng Gạch Creative Lab

Biến một bức ảnh thành một tượng mini 3D có thể sưu tầm theo phong cách gạch qua hai giai đoạn. Một tác vụ prototype tạo ra một hình ảnh khái niệm từ bức ảnh. Một tác vụ build biến hình ảnh đó thành một mô hình 3D có texture, và lấy ID của tác vụ prototype làm input_task_id.

POST /openapi/creative-lab/brick-figure/v1/prototype
POST /openapi/creative-lab/brick-figure/v1/build

POST/openapi/creative-lab/brick-figure/v1/prototype

Tạo một tác vụ prototype Brick Figure

Tạo ra một ảnh concept theo phong cách gạch lắp ráp từ một bức ảnh. Để xây dựng mô hình 3D, hãy truyền ID của tác vụ này vào build endpoint dưới dạng input_task_id. Để biết các trường của tác vụ, xem The Brick Figure prototype task object.

Request

POST

/openapi/creative-lab/brick-figure/v1/prototype

# Stage 1: generate a brick-style concept image
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

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

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Bức ảnh để chuyển thành minifigure gạch lắp ráp, dưới dạng URL công khai hoặc data URI (data:image/jpeg;base64,<dữ liệu ảnh mã hóa base64 của bạn>).
Ảnh phải là tệp JPG, JPEG, PNG hoặc WebP có dung lượng tối đa 20 MB.
Name
name
Type
string
Description
Tên cho tác vụ, tối đa 100 ký tự. Tên này sẽ được trả về trong trường name của tác vụ. Nếu tên dài hơn sẽ trả về lỗi 400.
Name
remove_background
Type
boolean
mặc định false
Description
Có xóa nền khỏi ảnh prototype hay không. true sẽ trả về ảnh PNG RGBA trong suốt, giúp bạn đặt chủ thể lên bất kỳ nền nào. Quá trình build cũng sẽ bắt đầu từ ảnh đã bỏ nền. Nếu Meshy không thể xóa nền, nó sẽ trả về ảnh kèm nền gốc, 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ụ prototype mới. Lấy thông tin tác vụ hoặc theo dõi trực tiếp cho đến khi status là SUCCEEDED. Sau đó truyền ID vào 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ể thực hiện. Ví dụ:
- Thiếu image_url.
- Ảnh không phải là tệp JPG, JPEG, PNG hoặc WebP.
- Ảnh quá nhỏ, vượt quá 20 MB, hoặc vượt quá số pixel tối đa.
- Meshy không thể tải ảnh xuống, ví dụ do URL trả về 404 hoặc hết thời gian chờ.
- Data URI không phải là base64 hợp lệ.
- Ảnh bị đánh dấu là nội dung nhạy cảm (NSFW).
Thông báo lỗi sẽ cho biết vấn đề gặp phải. Hãy sửa yêu cầu rồi gửi lại.
Name
401 - Unauthorized
Description
Thiếu khóa API hoặc khóa API không hợp lệ. Hãy kiểm tra header Authorization.
Name
402 - Payment Required
Description
Một trong các trường hợp sau xảy ra:
- Tài khoản không đủ tín dụng.
- Khóa API, không gian làm việc hoặc thành viên đã đạt giới hạn tín dụng.
- Tài khoản đang dùng gói miễn phí.
Hãy kiểm tra số tín dụng và gói của bạn, sau đó thử lại.
Name
403 - Forbidden
Description
Nhóm của bạn đã bật IP Filtering, và Meshy đã đánh dấu ảnh này vì sở hữu trí tuệ của bên thứ ba. Hãy gửi một ảnh mà bạn có quyền sử dụng.
Name
429 - Too Many Requests
Description
Một trong các giới hạn sau đã đạt tới:
- Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Hãy đợi vài giây rồi thử lại. Xem Rate limits.
- Có quá nhiều tác vụ của bạn đang chờ xử lý hoặc đang chạy. Hãy đợi một số tác vụ hoàn thành rồi thử lại.
- Với gói không giới hạn nhưng đã hết 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 đợi một tác vụ hoàn thành, hoặc nạp thêm tín dụng.
Name
500 - Internal Server Error
Description
Meshy gặp lỗi máy chủ, ví dụ do không thể chạy kiểm tra sở hữu trí tuệ trên ảnh. Meshy sẽ không tạo tác vụ, và hoàn lại bất kỳ khoản tín dụng nào đã bị trừ. Hãy thử lại yêu cầu.

POST/openapi/creative-lab/brick-figure/v1/build

Tạo một tác vụ build Brick Figure

Tạo ra minifigure 3D đã được áp texture từ một tác vụ prototype đã thành công. Để biết các trường của nó, xem Đối tượng tác vụ build Brick Figure.

Request

POST

/openapi/creative-lab/brick-figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

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

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
ID của tác vụ prototype cần build. Nó 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/brick-figure/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ụ prototype Brick Figure của bạn từ API sẽ trả về 404, kể cả một prototype được tạo trong ứng dụng web.
Name
name
Type
string
Description
Tên cho tác vụ, tối đa 100 ký tự. Tên này sẽ được trả về trong trường name của tác vụ. Tên dài hơn sẽ trả về 400.

Giá trị trả về

Trường result chứa ID của tác vụ build mới. Lấy tác vụ hoặc stream nó cho đến khi status là SUCCEEDED. Sau đó tải xuống GLB đã áp texture từ model_urls.glb. Để lấy OBJ thay thế, tải xuống model_urls.obj cùng với tệp vật liệu của nó từ model_urls.mtl.

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ụ prototype không phải là SUCCEEDED. Nếu nó vẫn đang chạy, hãy đợi rồi thử lại. Nếu nó đã thất bại hoặc bị hủy, hãy tạo một tác vụ prototype mới.
- Tác vụ prototype đã thành công nhưng không có hình ảnh. Hãy tạo một tác vụ prototype mới.
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ụ prototype Brick Figure nào mà tài khoản của bạn đã tạo bằng API. Một prototype được tạo trong ứng dụng web cũng sẽ trả về 404. Hãy gửi ID result từ một phản hồi tạo prototype.
Name
429 - Too Many Requests
Description
Một trong 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. Hãy đợi vài giây, sau đó thử lại. Xem Giới hạn tốc độ.
- Có quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Hãy đợi một số tác vụ hoàn tất, sau đó thử lại.
- Trên 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 đợi một tác vụ hoàn tất, hoặc nạp thêm tín dụng.

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

Lấy một tác vụ Brick Figure

Trả về một tác vụ prototype hoặc build. Đường dẫn phải khớp với giai đoạn của tác vụ. Một tác vụ build được yêu cầu qua /prototype/:id sẽ trả về 404, và một tác vụ prototype được yêu cầu qua /build/:id cũng vậy.

Để biết các trường, xem Đối tượng tác vụ prototype Brick Figure và Đối tượng tác vụ build Brick Figure.

Request

GET

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

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

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

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-brick-figure-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-brick-figure-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,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?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 chế độ 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 IP Filtering, và Meshy đã gắn cờ hình ảnh của tác vụ vì sở hữu trí tuệ của bên thứ ba. Các nhóm dùng gói Enterprise sẽ không gặp lỗi này. Hãy tạo tác vụ prototype từ một hình ảnh mà bạn có quyền sử dụng.
Name
404 - Not Found
Description
Không có tác vụ Brick Figure 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à 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/brick-figure/v1/(prototype|build)/:id

Xóa một tác vụ Brick Figure

Hủy một tác vụ Brick Figure. 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 bị hủy mà không được hoàn tín dụng, vì một worker đã bắt đầu xử lý nó. Một tác vụ có trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) không thể bị hủy.

Đường dẫn phải khớp với giai đoạn của tác vụ. Ví dụ, DELETE trên /prototype/:id với ID của một tác vụ build sẽ trả về 404.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/brick-figure/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 rỗng.

Các chế độ thất bạ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ụ Brick Figure 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ụ.

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

Stream nhiệm vụ Brick Figure

Stream các cập nhật của một nhiệm vụ Brick Figure dưới dạng Server-Sent Events (SSE). Đường dẫn phải khớp với giai đoạn của nhiệm vụ. Nếu không khớp, ví dụ như ID của một build task tại /prototype/:id/stream, stream sẽ gửi một sự kiện error với status_code: 404 rồi đóng lại.

Request

GET

/openapi/creative-lab/brick-figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/brick-figure/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-brick-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

Tham số

Name
id
Type
path
Description
ID nhiệm vụ từ phản hồi tạo.

Giá trị trả về

Một stream các đối tượng nhiệm vụ prototype hoặc build. Mỗi sự kiện chứa toàn bộ đối tượng nhiệm vụ, giống như những gì Lấy thông tin một nhiệm vụ Brick Figure trả về. Khi nhiệm 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 nhiệm vụ, stream sẽ gửi một sự kiện error thay thế, với status_code mà một yêu cầu get sẽ trả về.

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

Lấy danh sách tác vụ Brick Figure

Trả về các tác vụ Brick Figure của bạn trong 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, còn /build chỉ trả về các tác vụ build.

Request

GET

/openapi/creative-lab/brick-figure/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-brick-figure-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=***"
    ]
  }
]

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. Giá trị 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 gồm 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 Brick Figure

Một tác vụ prototype tạo ra một hình ảnh ý tưởng theo phong cách brick từ một bức ảnh. Để chuyển hình ảnh thành mô hình 3D, hãy truyền ID của tác vụ đến build endpoint dưới dạng input_task_id.

Thuộc tính

Example Brick Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-brick-figure-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=***"
  ]
}

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-brick-figure-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
Tỷ lệ 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 tác vụ 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 lúc đó.
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 lúc đó.
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 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 tác vụ đang ở trạng thái PENDING. 1 nghĩa là tác vụ sẽ bắt đầu tiếp theo. 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 đã hoàn trả (nếu có). Một yêu cầu trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại có giá trị là 0, vì Meshy sẽ hoàn trả tín dụng. Việc hủy chỉ hoàn trả tác vụ khi tác vụ đ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
image_urls
Type
array of strings
Description
URL tải xuống cho hình ảnh ý tưởng. Mảng này có một URL sau khi tác vụ thành công, và trống cho đến lúc đó.

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

Một tác vụ xây dựng (build task) tạo ra một mô hình minifigure 3D có texture từ một tác vụ prototype đã thành công. Các trường model_urls, thumbnail_url, và texture_urls của nó có cùng định dạng như trong đối tượng tác vụ Ảnh sang 3D.

Thuộc tính

Example Brick Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-brick-figure-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,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?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-brick-figure-build.
Name
name
Type
string
Description
name bạn đã gửi khi tạo tác vụ, hoặc "" nếu bạn không gửi.
Name
status
Type
string
Description
Trạng thái của tác vụ.
Các giá trị khả dụng:
- PENDING: đang chờ trong hàng đợi
- IN_PROGRESS: đang tạo kết quả
- SUCCEEDED: cuối cùng, có kết quả
- FAILED: cuối cùng, kèm 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 tác vụ 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. Là null cho đến lúc đó.
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. Là null cho đến lúc đó.
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 tài khoản Doanh nghiệp (Enterprise), vốn giữ kết quả API vô thời hạn, giá trị này là khoảng 100 năm sau. Xem Lưu giữ tài nguyên.
Name
preceding_tasks
Type
integer
Description
Vị trí của tác vụ trong hàng đợi khi tác vụ đang ở trạng thái PENDING. 1 nghĩa là tác vụ sẽ bắt đầu tiếp theo. 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. Là null trừ khi status là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số tín dụng bị tính cho tác vụ, sau khi đã hoàn lại (nếu có). Một yêu cầu trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại có giá trị 0, vì Meshy sẽ hoàn lại tín dụng. Việc hủy chỉ hoàn lại tín dụng cho tác vụ khi tác vụ đ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
prompt
Type
string
Description
Luôn là "" đối với một tác vụ xây dựng Brick Figure.
Name
negative_prompt
Type
string
Description
Luôn là "" đối với một tác vụ xây dựng Brick Figure, giống như prompt.
Name
texture_prompt
Type
string
Description
Luôn là "" đối với một tác vụ xây dựng Brick Figure, giống như prompt.
Name
texture_image_url
Type
string
Description
Luôn là "" đối với một tác vụ xây dựng Brick Figure, giống như prompt.
Name
model_urls
Type
object
Description
URL tải xuống cho mô hình 3D, dưới dạng một tệp GLB có texture và một tệp OBJ cùng với tệp MTL của nó.
- Name
  glb
  Type
  string
  Description
  URL tải xuống cho tệp GLB có texture.
- Name
  obj
  Type
  string
  Description
  URL tải xuống cho tệp OBJ, gồm hình học và UV.
- Name
  mtl
  Type
  string
  Description
  URL tải xuống cho tệp vật liệu MTL đi kèm với obj. Sử dụng tệp này cùng với obj và texture trong texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL tải xuống cho hình ảnh xem trước của mô hình.
Name
texture_urls
Type
array
Description
Các bản đồ texture, dưới dạng một mảng chứa một đối tượng giữ bản đồ màu nền (base color).
- Name
  base_color
  Type
  string
  Description
  URL tải xuống cho bản đồ màu nền.