Creative Lab — API Móc Khóa

Biến một bức ảnh nguồn thành một huy chương móc khóa có thể in 3D — một phù hiệu có độ sâu màu — qua hai giai đoạn: nguyên mẫu tạo ra một hình ảnh khái niệm được tô màu từ bức ảnh đầu vào của bạn, sau đó xây dựng biến hình ảnh khái niệm đó thành một mô hình 3D nổi. Hai giai đoạn này đượ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 Nhiệm Vụ Nguyên Mẫu Móc Khóa

Tạo một hình ảnh khái niệm được tô màu từ ảnh nguồn. ID nhiệm vụ được trả về là những gì bạn truyền dưới dạng input_task_id đến endpoint xây dựng. Tham khảo Đối Tượng Nhiệm Vụ Nguyên Mẫu Móc Khóa để 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 khái niệm sẵn sàng cho móc khóa. 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 công khai: Một URL có thể truy cập từ internet công cộng.
    • Data URI: Một Data URI mã hóa base64 của hình ảnh. Ví dụ về một Data URI: data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>.
  • Name
    name
    Type
    string
    Description

    Tên nhiệm vụ tùy chọn để 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 nguyên mẫu được trả về dưới dạng PNG RGBA trong suốt với nền đã được loại bỏ, để bạn có thể ghép đối tượng vào bất kỳ nền nào.

    Điều này chỉ kiểm soát hình ảnh mà endpoint này trả về. Nó tách biệt với tùy chọn xây dựng cùng tên (mặc định true), kiểm soát việc loại bỏ nền trước khi tạo hình nổi.

Trả Về

Thuộc tính result của phản hồi chứa id nhiệm vụ của nhiệm vụ nguyên mẫu móc khóa mới được tạo. Thăm dò endpoint Lấy Nhiệm Vụ hoặc đăng ký luồng cho đến khi nhiệm vụ đạt SUCCEEDED, sau đó truyền ID đó đến endpoint xây dựng dưới dạng input_task_id.

Các Chế Độ Thất Bại

  • Name
    400 - Bad Request
    Description

    Yêu cầu không chấp nhận được. 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 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ố lượng pixel tối đa.
    • URL không thể truy cập: image_url không thể tải xuống (404 hoặc timeout).
    • Data URI không hợp lệ: Chuỗi base64 bị lỗi.
    • Nội dung bị gắn cờ: Hình ảnh đầu vào bị gắn cờ bởi kiểm duyệt 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 nhiệm vụ này.

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ của mình.

Yêu Cầu

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>"
  }'

Phản Hồi

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Ví dụ nguyên mẫu
Bắt đầu với một ảnh nguồn, sau đó tạo hình ảnh nguyên mẫu được sử dụng bởi giai đoạn xây dựng móc khóa.
Ảnh nguồn được sử dụng làm đầu vào Móc Khóa Creative Lab
Đầu vào nguyên mẫu
Đầu ra nguyên mẫu Móc Khóa Creative Lab được tạo từ ảnh nguồn
Đầu ra nguyên mẫu
POST/openapi/creative-lab/keychain/v1/build

Tạo một Nhiệm Vụ Xây Dựng Móc Khóa

Tạo huy chương móc khóa có thể in 3D cuối cùng từ một nhiệm vụ nguyên mẫu đã thành công. Quá trình xây dựng chạy một đường ống bản đồ độ sâu trên hình ảnh khái niệm có màu của nguyên mẫu và xuất một hiện vật lưới duy nhất theo định dạng bạn yêu cầu. Tham khảo Đối tượng Nhiệm Vụ Xây Dựng 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 nhiệm vụ của một nhiệm vụ nguyên mẫu được tạo thông qua endpoint OpenAPI này. Nguyên mẫu phải được tạo với cùng khóa API, phải đạt trạng thái SUCCEEDED, và phải tạo ra chính xác một hình ảnh ứng viên.

    Nhiệm vụ nguyên mẫu được tạo thông qua ứng dụng web không được chấp nhận — endpoint xây dựng chỉ chấp nhận nhiệm vụ nguyên mẫu được tạo bởi POST /openapi/creative-lab/keychain/v1/prototype và từ chối bất kỳ nguồn nào khác với 404.

  • Name
    name
    Type
    string
    Description

    Tên nhiệm vụ tùy chọn cho mục đích hiển thị. Tối đa 100 ký tự.

options

Tham số điều chỉnh tùy chọn cho hình học relief. Mỗi trường có một 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

    Hình bóng viền của huy chương móc khóa. Các giá trị có sẵn:

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

    Chiều dài cạnh vuông giới hạn của 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 relief tối đa trên nề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 áp dụng cho relief 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 nền phẳng phía sau relief, 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 huy chương có được niêm phong như một bề mặt kín hay không. Đặt thành false cho một vỏ mở.

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

    Đường cong chuyển đổi ánh xạ các giá trị bản đồ độ sâu thành chiều cao relief. Các giá trị có sẵn:

    • 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 bản đồ độ sâu để các vùng tối hơn trở thành relief cao hơn.

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

    Độ mạnh làm mịn áp dụng cho bản đồ độ sâu trước khi trích xuất relief. Phạm vi: [0, 10].

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

    Hệ số nhân tỷ lệ dọc áp dụng trên relief_height_mm. Phạm vi: (0, 10].

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

    Ngưỡng thông thấp cho các giá trị bản đồ độ sâu; bất kỳ giá trị nào dưới 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 loại bỏ nền của hình ảnh khái niệm nguyên mẫu trước khi tạo relief.

    Tách biệt với tham số nguyên mẫu cùng tên (mặc định false), điều khiển xem hình ảnh nguyên mẫu có được trả về với độ trong suốt hay không.

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

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

output

Bộ chọn định dạng dây tùy chọn. Mặc định là glb.

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

    Gói hiện vật được trả về bởi quá trình xây dựng. Các giá trị có sẵn:

    • 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 hiện vật 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 nhiệm vụ của nhiệm vụ xây dựng móc khóa mới được tạo. Thăm dò endpoint Lấy một Nhiệm Vụ hoặc đăng ký luồng cho đến khi nhiệm vụ đạt trạng thái SUCCEEDED, sau đó tải xuống hiện vật từ mục nhập duy nhất trong model_urls.

Chế độ Thất bại

  • Name
    400 - Bad Request
    Description

    Yêu cầu không chấp nhận được. 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ệ.
    • Cha chưa thành công: Nhiệm vụ nguyên mẫu được tham chiếu chưa đạt trạng thái SUCCEEDED.
    • Không có ứng viên: Nhiệm vụ nguyên mẫu đã thành công nhưng không tạo ra hình ảnh ứng viên.
    • Tùy chọn ngoài phạm vi: Một trong các trường options nằm ngoài phạm vi hoặc tập hợ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 nhiệm vụ này.

  • Name
    404 - Not Found
    Description

    Nhiệm vụ nguyên mẫu được tham chiếu không tồn tại, thuộc về người dùng khác, hoặc được tạo thông qua ứng dụng web (chỉ các nhiệm vụ nguyên mẫu chế độ API mới được xây dựng).

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ của mình.

Yêu cầu

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"
    }
  }'

Phản hồi

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Ví dụ xây dựng
Nhiệm vụ xây dựng chuyển đổi hình ảnh nguyên mẫu đã chọn thành mô hình móc khóa có thể in 3D.
Xem trước mô hình xây dựng Móc Khóa Creative Lab
Xem trước mô hình xây dựng
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Truy xuất một nhiệm vụ Móc khóa

Truy xuất một nhiệm vụ nguyên mẫu hoặc xây dựng với một id nhiệm vụ hợp lệ. Đường dẫn URL phải khớp với giai đoạn của nhiệm vụ — một nhiệm vụ xây dựng được truy xuất qua /prototype/:id sẽ trả về 404, và ngược lại.

Tham khảo Đối tượng Nhiệm vụ Nguyên mẫu Móc khóa và Đối tượng Nhiệm vụ Xây dựng Móc khóa để biết cấu trúc phản hồi.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất cho nhiệm vụ móc khóa cần truy xuất.

Trả về

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

Yêu cầu

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}"

Phản hồi Nguyên mẫu

{
  "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=***"
  ]
}

Phản hồi Xây dựng

{
  "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 một Nhiệm vụ Móc khóa

Hủy một nhiệm vụ móc khóa. Nếu nhiệm vụ vẫn đang PENDING, các tín dụng tiêu thụ khi tạo sẽ được hoàn lại. Các nhiệm vụ đã IN_PROGRESS sẽ bị hủy mà không được hoàn lại (công nhân có thể đã đang tiêu tốn tài nguyên). Các nhiệm vụ đã đạt trạng thái cuối (SUCCEEDED, FAILED, CANCELED) không thể bị hủy.

Đường dẫn URL phải khớp với giai đoạn của nhiệm vụ — DELETE trên /prototype/:buildId trả về 404.

Tham số Đường dẫn

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất cho nhiệm vụ móc khóa cần hủy.

Trả về

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

Các Chế độ Thất bại

  • Name
    400 - Bad Request
    Description

    Nhiệm vụ đã ở trạng thái cuối và không thể bị hủy.

  • Name
    404 - Not Found
    Description

    Nhiệm 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.

Yêu cầu

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}"

Phản hồi

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Phát trực tuyến một nhiệm vụ Móc khóa

Phát trực tuyến các cập nhật thời gian thực cho một nhiệm 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 nhiệm vụ — mở một luồng tại /prototype/:buildId/stream sẽ phát ra một event: error payload duy nhất với status_code: 404 và đóng luồng.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất cho nhiệm vụ móc khóa để phát trực tuyến.

Trả về

Trả về một luồng các đối tượng nhiệm vụ Keychain Prototype hoặc Keychain Build dưới dạng Server-Sent Events. Đối với các nhiệm 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.

Yêu cầu

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}"

Luồng Phản hồi

// 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ê Nhiệm vụ Móc khóa

Lấy danh sách phân trang các nhiệm vụ móc khóa của bạn cho một giai đoạn duy nhất. Đường dẫn URL chọn giai đoạn — /prototype trả về các nhiệm vụ nguyên mẫu; /build trả về các nhiệm vụ xây dựng. Các nhiệm 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 là prototype hoặc build. Bộ sưu tập chỉ trả về các nhiệm vụ có giai đoạn khớp với URL — lấy /prototype không bao giờ trả về các nhiệm vụ xây 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 cho phép là 50 mục.

  • Name
    sort_by
    Type
    string
    mặc định -created_at
    Description

    Trường để sắp xếp. Các giá trị có sẵn:

    • +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 nhiệm vụ theo giai đoạn — hoặc đối tượng nhiệm vụ nguyên mẫu móc khóa khi liệt kê /prototype hoặc đối tượng nhiệm vụ xây dựng móc khóa khi liệt kê /build.

Yêu cầu

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}"

Phản hồi (Liệt kê Nhiệm vụ Nguyên mẫu)

[
  {
    "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 Nhiệm vụ Nguyên mẫu Móc khóa

Đối tượng Nhiệm 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 ra một hình ảnh khái niệm có màu từ một bức ảnh nguồn. Kết quả đầu ra của giai đoạn này được liên kết vào giai đoạn xây dựng thông qua input_task_id.

Thuộc tính

  • Name
    id
    Type
    string
    Description

    Định danh duy nhất cho nhiệm vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp k cho id nhiệm 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 nhiệm vụ. Giá trị là creative-lab-keychain-prototype.

  • Name
    name
    Type
    string
    Description

    Tên nhiệm vụ được cung cấp khi nhiệm 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 nhiệm vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Tiến độ của nhiệm vụ. Nếu nhiệm vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi nhiệm vụ đã thành công, điều này sẽ trở thành 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Dấu thời gian khi nhiệm vụ đượ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 12:00:00 PM 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 nhiệm vụ được bắt đầu, tính bằng mili giây. Nếu nhiệm vụ 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 nhiệm vụ được hoàn thành, tính bằng mili giây. Nếu nhiệm vụ 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ả nhiệm vụ hết hạn, tính bằng mili giây.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng nhiệm vụ trước đó.

    Giá trị của trường này chỉ có ý nghĩa nếu trạng thái nhiệm vụ là PENDING.

  • Name
    task_error
    Type
    object
    Description

    Chi tiết lỗi cho các nhiệm vụ thất bại. Xem Lỗi để tham khảo đầy đủ đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số lượng tín dụng đã tiêu thụ bởi nhiệm vụ này. Có mặt khi trạng thái nhiệm vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các nhiệm vụ FAILED (tín dụng được hoàn lại khi thất bại).

  • Name
    image_urls
    Type
    array of strings
    Description

    Các URL có thể tải xuống cho các ứng viên hình ảnh khái niệm được tạo ra bởi nhiệm 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 phiên bản tương lai có thể hiển thị nhiều ứng viên mà không cần thay đổi phá vỡ.

Ví dụ về Đối tượng Nhiệm vụ Nguyên mẫu Móc khóa

{
  "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ụ Xây dựng Móc khóa

Đối tượng Tác vụ Xây dựng Móc khóa là một đơn vị công việc mà Meshy theo dõi để tạo ra 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 xây dựng chạy một đường ống nổi bật bản đồ độ sâu trên hình ảnh ý tưởng của nguyên mẫu và xuất bản một lưới hiện vật duy nhất theo định dạng mà người 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 trố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

    Tiến độ của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, điều 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 thành, tính bằng mili giây.

  • Name
    expires_at
    Type
    timestamp
    Description

    Dấu thời gian khi kết quả của 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ụ 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 để tham khảo đầy đủ đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số lượng tín dụng đã 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

    URL có thể tải xuống cho hiện vật được tạo, được khóa theo tên hiện vật. Luôn chứa chính xác một mục nhập — định dạng được yêu cầu thông qua output.format của yêu cầu xây dựng. Khóa khớp với định dạng được yêu cầu:

    • Name
      glb
      Type
      string
      Description

      URL có thể tải xuống cho 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 cho 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 cho một gói zip của mọi hiện vật 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=***"
  }
}