Creative Lab — Vinyl Figure API

Biến một tấm ảnh gốc thành một tượng sưu tập 3D dạng vinyl đầu to qua hai giai đoạn: prototype tạo ra một hình ảnh ý tưởng theo phong cách từ ảnh đầu vào của bạn, sau đó build biến hình ảnh ý tưởng đó 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/vinyl-figure/v1/prototype
POST /openapi/creative-lab/vinyl-figure/v1/build

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

Create a Vinyl Figure Prototype Task

Tạo một ảnh concept theo phong cách tượng vinyl duy nhất từ ảnh gốc. ID tác vụ được trả về chính là giá trị bạn truyền vào làm input_task_id cho endpoint build. Tham khảo The Vinyl Figure Prototype Task Object để 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 gốc để Meshy tạo phong cách thành một tượng vinyl đầu to. 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 mã hóa base64 của hình ảnh. 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 cho mục đích hiển thị. Tối đa 100 ký tự.
Name
remove_background
Type
boolean
mặc định false
Description
Khi được đặt thành true, ảnh prototype được trả về dưới dạng PNG RGBA trong suốt với phần nền đã được xóa, để bạn có thể ghép chủ thể lên 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 vinyl vừa được tạo. Hãy poll endpoint Get a Task 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 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: 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 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/vinyl-figure/v1/prototype

# Stage 1: generate a vinyl-figure-style concept image
curl https://api.meshy.ai/openapi/creative-lab/vinyl-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": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
}

Prototype example

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

Source photo used as the Creative Lab Vinyl Figure input — Prototype input

Big-head vinyl figure prototype image generated from the source photo — Prototype output

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

Create a Vinyl Figure Build Task

Tạo tượng vinyl 3D có texture cuối cùng từ một tác vụ prototype đã thành công. Quá trình build chạy cùng pipeline image-to-3D như Ảnh sang 3D, vì vậy định dạng đối tượng phản hồi và danh sách các URL đầu ra hoàn toàn giống nhau. Tham khảo Đối tượng tác vụ Vinyl Figure Build để biết 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ụ prototype được tạo qua cùng endpoint OpenAPI này. Prototype 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 tác vụ prototype được tạo qua webapp không được chấp nhận — endpoint build chỉ chấp nhận các tác vụ prototype được tạo bởi POST /openapi/creative-lab/vinyl-figure/v1/prototype và từ chối mọi nguồn khác với mã lỗi 404.
Name
name
Type
string
Description
Tên tác vụ tùy chọn để hiển thị. Tối đa 100 ký tự.

Giá trị trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ build vinyl figure vừa được tạo. Hãy poll endpoint Get a Task hoặc đăng ký stream cho đến khi tác vụ đạt trạng thái SUCCEEDED, sau đó tải xuống 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 ưu tiên OBJ).

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ố: input_task_id là bắt buộc.
- UUID không hợp lệ: input_task_id không phải là một UUID hợp lệ.
- Tác vụ cha chưa thành công: Tác vụ prototype được tham chiếu chưa đạt trạng thái SUCCEEDED.
- Không có ứng viên: Tác vụ prototype đã 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 tác vụ này.
Name
404 - Not Found
Description
Tác vụ prototype đượ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 tác vụ prototype ở chế độ API mới có thể được nối chuỗi 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/vinyl-figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
  }'

Response

{
  "result": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef"
}

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

Truy xuất một Tác vụ Tượng Vinyl

Truy xuất một tác vụ prototype hoặc build với một 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ụ Prototype Tượng Vinyl và Đối tượng Tác vụ Build Tượng Vinyl để 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 vinyl cần truy xuất.

Kết quả trả về

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

Request

GET

/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "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/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

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

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

Hủy một tác vụ tượng Vinyl. Nếu tác vụ vẫn đang ở trạng thái PENDING, số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại. Các tác vụ đã ở trạng thái IN_PROGRESS sẽ bị hủy nhưng 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 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 Vinyl 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 chế độ 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ề 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/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

Stream a Vinyl Figure Task

Truyền (stream) cập nhật theo thời gian thực cho một tác vụ tượng vinyl 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 và đóng stream.

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ tượng vinyl cần truyền (stream).

Giá trị trả về

Trả về một stream các đối tượng tác vụ Vinyl Figure Prototype hoặc Vinyl Figure Build dưới dạng Server-Sent Events. Mỗi khung dữ liệu (frame) mang toàn bộ đối tượng tác vụ của giai đoạn đó — cùng cấu trúc mà endpoint Get trả về — vì vậy 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/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/stream

curl -N https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/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": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

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

Danh sách các tác vụ Vinyl Figure

Truy xuất danh sách được phân trang các tác vụ vinyl figure 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ụ prototype; /build trả về các tác vụ build. Các tác vụ thuộc giai đoạn còn lại sẽ 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
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 gọi /prototype sẽ không bao giờ trả về các 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 dùng cho phân trang.
Name
page_size
Type
integer
mặc định 10
Description
Giới hạn kích thước trang. Số lượng tối đa cho phép là 100 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 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.

Giá trị 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 — có thể là đối tượng tác vụ prototype vinyl figure khi liệt kê /prototype hoặc đối tượng tác vụ build vinyl figure khi liệt kê /build.

Request

GET

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

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
    "type": "creative-lab-vinyl-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1752969600000,
    "started_at": 1752969604000,
    "finished_at": 1752969630000,
    "expires_at": 1753228830000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Đối tượng Task Nguyên Mẫu Tượng Vinyl

Đối tượng Task Nguyên Mẫu Tượng Vinyl 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 tượng vinyl từ một ảnh gốc. Đầ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
Mã đị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) 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-vinyl-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 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.
Một 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 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 task được bắt đầu, tính bằng mili giây. Nếu task chưa 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 tất, tính bằng mili giây. Nếu task chưa hoàn tất, 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 đủ của đố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. 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 đượ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 ứng viên ảnh concept được tạo ra bởi task 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ỡ (breaking change).

Example Vinyl Figure Prototype Task Object

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

The Vinyl Figure Build Task Object

Vinyl Figure Build Task object là một đơn vị công việc mà Meshy theo dõi để tạo ra một tượng vinyl 3D có texture từ một prototype task đã thành công. Nó chạy cùng 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-vinyl-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 các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress của task. Nếu task chưa được 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 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 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 rỗng đối với vinyl figure build. Có mặt để tương thích liên endpoint với cấu trúc V2ImageTo3DTaskResponse dùng chung được sử dụng bởi Ảnh sang 3D.
Name
negative_prompt
Type
string
Description
Luôn rỗng đối với vinyl figure build. Có mặt để tương thích liên endpoint.
Name
texture_prompt
Type
string
Description
Luôn rỗng đối với vinyl figure build. Có mặt để tương thích liên endpoint.
Name
texture_image_url
Type
string
Description
Luôn rỗng đối với vinyl figure build. Có mặt để tương thích liên endpoint.
Name
model_urls
Type
object
Description
Các URL có thể tải xuống cho mô hình 3D đã tạo. Vinyl figure build tạo ra một file GLB có texture cùng với cặp OBJ + MTL cho các pipeline ưu tiên Wavefront OBJ. Cấu trúc trường 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 thay đổi phá vỡ (breaking change).
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống cho file GLB có texture.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống cho file Wavefront OBJ (hình học + UV).
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống cho file vật liệu MTL đi kèm OBJ. Ghép cặ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 file 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 (base color map).
- Name
  base_color
  Type
  string
  Description
  URL có thể tải xuống cho ảnh bản đồ màu cơ bản.

Example Vinyl Figure Build Task Object

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "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/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}