Creative Lab — API móc khóa

Biến ảnh nguồn thành một huy chương móc khóa có thể in 3D — một phù hiệu dạng phù điêu độ sâu được tô màu — qua hai giai đoạn: prototype tạo một hình ảnh ý tưởng được tô màu 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 phù điêu. Hai giai đoạn được liên kết thông qua input_task_id.

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

Tạo tác vụ nguyên mẫu móc khóa

Tạo một hình ảnh ý tưởng đã được tô màu từ ảnh nguồn. ID tác vụ được trả về là giá trị bạn truyền dưới dạng input_task_id cho endpoint build. Tham khảo The Keychain Prototype Task Object để biết cấu trúc phản hồi.

Tham số

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

    Ảnh nguồn để Meshy tô màu thành hình ảnh ý tưởng sẵn sàng cho móc khóa. 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: Một URL có thể truy cập từ internet công cộng.
    • Data URI: Data URI được mã hóa base64 của hình ảnh. Ví dụ về data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • 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 móc khóa mới được tạo. Thăm dò endpoint Get a Task hoặc đăng ký stream cho đến khi tác vụ đạt SUCCEEDED, sau đó truyền ID đó đến build endpoint dưới dạng input_task_id.

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 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ố 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ệ.
  • 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/keychain/v1/prototype
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/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"
}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain prototype output generated from the source photo
Prototype output
POST/openapi/creative-lab/keychain/v1/build

Tạo tác vụ build móc khóa

Tạo medallion móc khóa cuối cùng có thể in 3D từ một tác vụ prototype đã thành công. Quá trình build chạy pipeline phù điêu depth-map trên hình ảnh concept đã tô màu của prototype và xuất một artifact lưới duy nhất theo định dạng bạn yêu cầu. Tham khảo Đối tượng tác vụ build móc khóa để 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 khóa API, phải đã đạt SUCCEEDED, và phải tạo ra đúng một ảnh ứng viên.

    Các tác vụ prototype được tạo thông 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/keychain/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 dùng 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 phù điêu. 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
    badge_shape
    Type
    string
    mặc định circle
    Description

    Silhouette đường viền của medallion móc khóa. Các giá trị khả dụng:

    • circle (mặc định)
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    mặc định 40
    Description

    Độ dài cạnh của hình vuông bao quanh móc khóa, tính bằng milimét. Phạm vi: (0, 400].

  • Name
    relief_height_mm
    Type
    number
    mặc định 2.2
    Description

    Chiều cao phù điêu tối đa phía trên phần đế, tính bằng milimét. Phạm vi: [0, 20].

  • Name
    relief_offset_mm
    Type
    number
    mặc định 0
    Description

    Độ lệch dọc được áp dụng cho phù điêu trước khi đùn, tính bằng milimét. Phạm vi: [0, 20].

  • Name
    base_thickness_mm
    Type
    number
    mặc định 0.1
    Description

    Độ dày của tấm đế phẳng phía sau phù điêu, tính bằng milimét. Phạm vi: [0, 20].

  • Name
    has_closed_back
    Type
    boolean
    mặc định true
    Description

    Mặt sau của medallion có được bịt kín như một bề mặt đóng hay không. Đặt thành false cho vỏ mở.

  • Name
    relief_curve
    Type
    string
    mặc định linear
    Description

    Đường cong chuyển đổi ánh xạ các giá trị depth-map sang chiều cao phù điêu. Các giá trị khả dụng:

    • linear (mặc định)
    • gamma
    • s-curve
  • Name
    curve_param
    Type
    number
    mặc định 1.0
    Description

    Tham số hình dạng cho đường cong chuyển đổi (chỉ có ý nghĩa khi relief_curve là gamma). Phạm vi: (0, 10].

  • Name
    invert_depth
    Type
    boolean
    mặc định false
    Description

    Đảo ngược cách diễn giải depth-map để các vùng tối hơn trở thành phù điêu cao hơn.

  • Name
    smoothing
    Type
    number
    mặc định 0.24
    Description

    Cường độ làm mượt được áp dụng cho depth map trước khi trích xuất phù điêu. Phạm vi: [0, 10].

  • Name
    relief_scale
    Type
    number
    mặc định 1.0
    Description

    Hệ số nhân tỷ lệ theo chiều dọc được áp dụng bên trên relief_height_mm. Phạm vi: (0, 10].

  • Name
    depth_threshold
    Type
    number
    mặc định 0.1
    Description

    Ngưỡng low-pass cho các giá trị depth-map; mọi giá trị thấp hơn mức này sẽ bị kẹp về không. Phạm vi: [0, 1].

  • Name
    remove_background
    Type
    boolean
    mặc định true
    Description

    Tự động xóa nền của hình ảnh concept từ prototype trước khi tạo phù điêu.

  • Name
    export_resolution
    Type
    integer
    mặc định 512
    Description

    Độ phân giải lưới được dùng để xuất (export). Phạm vi: [64, 2048].

output

Bộ chọn wire-format tùy chọn. Mặc định là glb.

  • Name
    format
    Type
    string
    mặc định glb
    Description

    Gói artifact được trả về bởi quá trình build. Các giá trị khả dụng:

    • glb (mặc định) — trả về một model.glb duy nhất dưới model_urls.glb.
    • obj — nén model.obj + model.mtl + texture.png và trả về gói dưới model_urls.obj.
    • zip — nén mọi artifact mà trình tạo phát ra và trả về gói 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ụ build móc khóa mới được tạo. Poll endpoint Lấy một tác vụ hoặc đăng ký stream cho đến khi tác vụ đạt SUCCEEDED, sau đó tải artifact xuống từ mục duy nhất trong model_urls.

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 thường gặp:

    • 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ệ.
    • Parent chưa thành công: Tác vụ prototype được tham chiếu chưa đạt 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.
    • Options 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ụ 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 thông qua webapp (chỉ các tác vụ prototype ở mode API mới có thể nối chuỗi vào build).

  • 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/keychain/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/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": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
The build task converts the selected prototype image into a 3D-printable keychain model.
Creative Lab Keychain build model preview
Build model preview
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Truy xuất một tác vụ móc khóa

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 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 móc khóa và Đối tượng tác vụ bản dựng móc khóa để 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ụ móc khóa cần truy xuất.

Trả về

Phản hồi chứa đối tượng tác vụ móc khóa. Cấu trúc phụ thuộc vào giai đoạn đã được yêu cầu.

Request

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

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

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-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-keychain-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,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Xóa tác vụ móc khóa

Hủy một tác vụ móc khóa. 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ụ đã IN_PROGRESS sẽ bị hủy mà không được hoàn lại (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ụ móc khóa cần hủy.

Trả về

Trả về 204 No Content khi thành công với phần thân trố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ề 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/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/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/keychain/v1/(prototype|build)/:id/stream

Truyền phát một tác vụ móc khóa

Truyền phát các cập nhật theo thời gian thực cho một tác vụ móc khóa qua Server-Sent Events (SSE). Đường dẫn URL phải khớp với giai đoạn của tác vụ — mở một luồng tại /prototype/:buildId/stream sẽ phát ra một payload event: error duy nhất với status_code: 404 và đóng luồng.

Tham số

  • Name
    id
    Type
    path
    Description

    Mã định danh duy nhất của tác vụ móc khóa cần truyền phát.

Trả về

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

Request

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

Liệt kê tác vụ móc khóa

Truy xuất danh sách phân trang các tác vụ móc khóa của bạn cho một giai đoạn. Đường dẫn URL 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ụ bản dựng. 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 không bao giờ trả về tác vụ bản dựng và ngược lại.

Tham số truy vấn

  • Name
    page_num
    Type
    integer
    mặc định 1
    Description

    Số trang cho 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 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ụ nguyên mẫu móc khóa khi liệt kê /prototype hoặc đối tượng tác vụ bản dựng móc khóa khi liệt kê /build.

Request

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-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 móc khóa

Đối tượng Tác vụ Nguyên mẫu móc khóa là một đơn vị công việc mà Meshy theo dõi để tạo một hình ảnh ý tưởng được tô màu từ ảnh nguồn. Đầu ra của giai đoạn này được nối chuỗi vào giai đoạn 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 k-sortable 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-keychain-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 khi tác vụ được tạo, tính bằng mili giây.

    Một dấu thời gian biểu thị số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, tuân 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 tác vụ được bắt đầu, tính bằng mili giây. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Dấu thời gian khi tác vụ được hoàn tất, tính bằng mili giây. Nếu tác vụ 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ả 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 đầy đủ về đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số lượng 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 trả 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 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ề chính xác một ứng viê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 ứng viên mà không gây thay đổi phá vỡ tương thích.

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-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ụ Dựng móc khóa

Đối tượng Tác vụ Dựng móc khóa là một đơn vị công việc mà Meshy theo dõi để tạo lưới móc khóa 3D cuối cùng từ một tác vụ nguyên mẫu đã thành công. Quá trình dựng chạy một pipeline phù điêu bản đồ độ sâu trên hình ảnh ý tưởng của nguyên mẫu và xuất bản một artifact lưới duy nhất ở định dạng mà bên gọi đã yêu cầu.

Thuộc tính

  • Name
    id
    Type
    string
    Description

    Đị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-keychain-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 đượ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 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ố lượng 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 artifact đã tạo, được lập khóa theo tên artifact. Luôn chứa đúng một mục — định dạng được yêu cầu thông qua output.format của yêu cầu build. Khóa khớp với định dạng đã yêu cầu:

    • Name
      glb
      Type
      string
      Description

      URL có thể tải xuống đến tệp GLB. Có mặt khi output.format là glb (mặc định).

    • Name
      obj
      Type
      string
      Description

      URL có thể tải xuống đến một gói zip chứa model.obj, model.mtl, và texture.png. Có mặt khi output.format là obj.

    • Name
      bundle_zip
      Type
      string
      Description

      URL có thể tải xuống đến một gói zip của mọi artifact mà trình tạo phát ra. Có mặt khi output.format là zip.

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-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,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}