Creative Lab — Figure API

Biến một bức ảnh gốc thành một tượng 3D có thể sưu tầm theo phong cách chibi qua hai giai đoạn: prototype tạo ra một hình ảnh khái niệm được tạo phong cách từ ảnh đầu vào của bạn, sau đó build biến hình ảnh khái niệm đó thành một mô hình 3D có texture. Hai giai đoạn được liên kết với nhau thông qua input_task_id.

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

Create a Figure Prototype Task

Tạo một hình ảnh concept theo phong cách chibi từ ảnh gốc. 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 tượng để biết cấu trúc phản hồi.

Tham số

  • Name
    image_url
    Type
    string
    Bắt buộc
    Description

    Ảnh gốc để Meshy tạo phong cách tượng chibi. 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 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ủa hình ảnh được mã hóa base64. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu hình ảnh được mã hóa base64 của bạn>.
  • 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 prototype sẽ được trả về dưới dạng PNG RGBA trong suốt với nền đã được 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 tượng 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 hợp lệ. 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 phải là đị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ố 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 nội dung nhạy cảm (NSFW) hoặc sở hữu trí tuệ.
  • 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/figure/v1/prototype
# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/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"
}
Ví dụ prototype
Bắt đầu với một ảnh chân dung gốc, sau đó tạo hình ảnh prototype được sử dụng bởi giai đoạn build.
Ảnh chân dung gốc được dùng làm đầu vào cho Creative Lab Figure
Đầu vào prototype
Hình ảnh prototype tượng theo phong cách chibi được tạo ra từ ảnh gốc
Đầu ra prototype
POST/openapi/creative-lab/figure/v1/build

Create a Figure Build Task

Tạo tượng 3D có texture cuối cùng từ một task nguyên mẫu (prototype) đã thành công. Quá trình build chạy cùng pipeline ảnh sang 3D như Ảnh sang 3D, vì vậy định dạng đối tượng phản hồi và danh sách URL đầu ra hoàn toàn khớp nhau. Tham khảo The Figure Build Task Object để biết hình dạng 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 chính xác một ảnh ứng viên.

    Các task 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 task nguyên mẫu được tạo bởi POST /openapi/creative-lab/figure/v1/prototype và sẽ từ chối bất kỳ nguồn khác với mã lỗi 404.

  • Name
    name
    Type
    string
    Description

    Tên task tùy chọn để hiển thị. Tối đa 100 ký tự.

Kết quả trả về

Thuộc tính result của phản hồi chứa id của task xây dựng tượng mới được tạo. Hãy poll endpoint Get a Task hoặc đăng ký stream cho đến khi task đạt trạng thái SUCCEEDED, sau đó tải xuống GLB có texture từ model_urls.glb (hoặc cặp OBJ + MTL từ model_urls.obj và model_urls.mtl nếu pipeline downstream của bạn thích dùng OBJ hơn).

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

  • Name
    400 - Bad Request
    Description

    Yêu cầu không hợp lệ. 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ệ.
    • Task gốc 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ó ứng viên: Task nguyên mẫu đã thành công nhưng không tạo ra ảnh ứng viên nào.
  • 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ể liên kết chuỗi sang build).

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ.

Request

POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/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"
}
Build example
Task build biến ảnh nguyên mẫu đã chọn thành một mô hình 3D có texture có thể tải xuống.
Creative Lab Figure build model preview
Build model preview
GET/openapi/creative-lab/figure/v1/(prototype|build)/:id

Retrieve a Figure Task

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 truy xuất qua /prototype/:id sẽ trả về 404, và ngược lại.

Tham khảo Đối tượng Tác vụ Figure Prototype và Đối tượng Tác vụ Figure Build để 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ụ tượng cần truy xuất.

Kết quả trả về

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

Request

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

# Build
curl https://api.meshy.ai/openapi/creative-lab/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-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-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": 20,
  "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=***"
    }
  ]
}
DELETE/openapi/creative-lab/figure/v1/(prototype|build)/:id

Xóa tác vụ Figure

Hủy một tác vụ tượng. 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ụ đã IN_PROGRESS sẽ bị hủy mà không được hoàn tiền (worker có thể đã đang 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

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất của tác vụ tượng cần hủy.

Kết quả trả về

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

Các trường hợp lỗ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ề một 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/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/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/figure/v1/(prototype|build)/:id/stream

Stream một Tác vụ Tượng

Stream cập nhật theo thời gian thực cho một tác vụ tượng 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 stream tại /prototype/:buildId/stream sẽ phát ra một payload event: error duy nhất với status_code: 404 rồi đóng stream.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất cho tác vụ tượng cần stream.

Giá trị trả về

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

Request

GET
/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/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 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-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}
GET/openapi/creative-lab/figure/v1/(prototype|build)

List Figure Tasks

Truy xuất một danh sách được phân trang các tác vụ tượng của bạn cho một giai đoạn duy nhất. Đường dẫn URL sẽ chọn giai đoạn — /prototype trả về các tác vụ nguyên mẫu; /build trả về các tác vụ build. Các tác vụ từ giai đoạn còn lại sẽ không được bao gồm trong cả hai phản hồi.

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 lấy /prototype sẽ không bao giờ trả về các tác vụ build 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 tăng dần.
    • -created_at: Sắp xếp theo thời gian tạo giảm dần.

Returns

Trả về một danh sách được phân trang của đối tượng tác vụ theo từng giai đoạn — hoặc là đối tượng tác vụ nguyên mẫu tượng khi liệt kê /prototype hoặc đối tượng tác vụ build tượng khi liệt kê /build.

Request

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

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/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-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=***"
    ]
  }
]

The Figure Prototype Task Object

Đối tượng Figure Prototype Task là một đơn vị công việc mà Meshy theo dõi để tạo ra một ảnh concept theo phong cách chibi từ một bức ảnh nguồn. Đầ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 task. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) làm chi tiết triển khai cho id của task, 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 task. Giá trị là creative-lab-figure-prototype.

  • 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 số PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Tiến độ 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.

    Dấu thời gian đại diện cho 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 diễn 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 khi task được bắt đầu, tính bằng mili giây. Nếu task 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 task hoàn thành, tính bằng mili giây. Nếu task 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 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.

    Giá trị của trường này chỉ có ý nghĩa khi trạng thái của task 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ố lượng tín dụng đã bị tiêu thụ bởi task này. Có mặt khi trạng thái task là PENDING, IN_PROGRESS, hoặc SUCCEEDED. 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
    image_urls
    Type
    array of strings
    Description

    Các URL có thể tải xuống cho những ứng viên ảnh concept được tạo ra bởi task 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ương thích.

Example Figure Prototype Task Object

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

The Figure Build Task Object

Đối tượng Figure Build Task là một đơn vị công việc mà Meshy theo dõi để tạo ra một tượng 3D có texture từ một prototype task đã thành công. Nó chạy cùng một pipeline image-to-3D được sử dụng bởi Ảnh sang 3D, vì vậy các trường đầu ra phản ánh task object của endpoint đó.

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-figure-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 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ả 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 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 đã tiêu thụ bởi task này. Trả về 0 cho các task FAILED (tín dụng được hoàn lại khi thất bại).

  • Name
    prompt
    Type
    string
    Description

    Luôn trống đối với figure build. Có mặt để tương thích liên endpoint với hình dạng V2ImageTo3DTaskResponse dùng chung được sử dụng bởi Ảnh sang 3D.

  • Name
    negative_prompt
    Type
    string
    Description

    Luôn trống đối với figure build. Có mặt để tương thích liên endpoint.

  • Name
    texture_prompt
    Type
    string
    Description

    Luôn trống đối với figure build. Có mặt để tương thích liên endpoint.

  • Name
    texture_image_url
    Type
    string
    Description

    Luôn trống đối với figure build. Có mặt để tương thích liên endpoint.

  • Name
    model_urls
    Type
    object
    Description

    URL có thể tải xuống cho mô hình 3D được tạo. Figure build phát ra một tệp GLB có texture cùng với cặp OBJ + MTL cho các pipeline ưa chuộng Wavefront OBJ. Hình dạng trường này khớp với đối tượng model_urls của Ảnh sang 3D để các định dạng bổ sung trong tương lai có thể được thêm vào mà không gây phá vỡ tương thích.

    • Name
      glb
      Type
      string
      Description

      URL có thể tải xuống cho tệp GLB có texture.

    • Name
      obj
      Type
      string
      Description

      URL có thể tải xuống cho tệp Wavefront OBJ (hình học + UV).

    • Name
      mtl
      Type
      string
      Description

      URL có thể tải xuống cho tệp vật liệu MTL đi kèm OBJ. Kết hợp với obj và mục từ texture_urls[0].base_color.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL có thể tải xuống cho ảnh thu nhỏ của tệp mô hình.

  • Name
    texture_urls
    Type
    array
    Description

    Một mảng các đối tượng URL texture được tạo bởi task này. Hiện tại chứa một đối tượng duy nhất với bản đồ màu cơ bản.

    • Name
      base_color
      Type
      string
      Description

      URL có thể tải xuống cho hình ảnh bản đồ màu cơ bản.

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-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": 20,
  "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=***"
    }
  ]
}