Creative Lab — API Móc khóa

Biến một tấm ảnh nguồn thành huy hiệu móc khóa có thể in 3D — một bức phù điêu độ sâu được tô màu theo hình dạng huy hiệu — qua hai giai đoạn: prototype tạo ra một hình ảnh khái niệm được tô màu 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 dạng phù điêu. Hai giai đoạn này được liên kết với nhau 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

Create a Keychain Prototype Task

Tạo một hình ảnh concept đã tô màu từ ảnh nguồn. ID tác vụ 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ụ Keychain Prototype để 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 concept sẵn sàng cho keychain. 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 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ủa bạn được mã hóa base64>.
  • Name
    name
    Type
    string
    Description

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

    Tên này gắn nhãn cho tác vụ trong bảng điều khiển và danh sách tác vụ của bạn. Nó không được khắc lên móc khóa — hãy dùng name_text cho mục đích đó.

  • Name
    name_text
    Type
    string
    Description

    Văn bản để khắc lên móc khóa, chẳng hạn như tên thú cưng hoặc tên người. Tối đa 10 ký tự, được tính theo ký tự Unicode chứ không phải byte, vì vậy một tên tiếng Trung, Nhật hoặc Hàn dài 10 ký tự vẫn được chấp nhận. Bỏ qua tham số này nếu muốn tạo móc khóa không có khắc chữ.

    Khoảng trắng xung quanh sẽ được cắt bỏ và các ký tự định dạng vô hình sẽ bị loại bỏ trước khi văn bản được sử dụng. Giá trị kết quả được trả về dưới dạng name_text trong đối tượng tác vụ prototype, để bạn có thể xác nhận chính xác nội dung sẽ được khắc trước khi thanh toán cho giai đoạn build.

    Việc khắc chữ được áp dụng ở đây, tại giai đoạn prototype. Giai đoạn build sẽ tự động kế thừa nó và không chấp nhận name_text riêng.

    Khi văn bản không phải là ASCII thuần túy, hãy gửi nội dung yêu cầu dưới dạng UTF-8 và đặt Content-Type: application/json; charset=utf-8. Một số HTTP client — bao gồm Invoke-RestMethod của Windows PowerShell — mã hóa nội dung theo ISO-8859-1 theo mặc định, khiến mọi ký tự không thuộc bảng chữ cái Latin âm thầm bị chuyển thành ? trước khi đến được Meshy. API không thể phân biệt điều đó với một nội dung khắc chữ mà bạn thực sự yêu cầu.

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

    Khi được đặt thành true, hình ảnh prototype được trả về dưới dạng PNG RGBA trong suốt với nền đã được xóa, để bạn có thể ghép chủ thể lên 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 build cùng tên (mặc định true), vốn kiểm soát việc xóa nền trước khi tạo relief.

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ụ keychain prototype vừa được tạo. 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 trường hợp thất bạ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á dung lượng file 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 định dạng.
    • Nội dung khắc quá dài: name_text dài hơn 10 ký tự. Yêu cầu sẽ bị từ chối thay vì bị cắt ngắn, vì vậy bạn sẽ không bao giờ bị tính phí cho một móc khóa được khắc với tên bị rút gọn.
    • Nội dung bị gắn cờ: Hình ảnh đầu vào bị gắn cờ bởi hệ thống moderation nội dung nhạy cảm (NSFW) hoặc sở hữu trí tuệ, hoặc nội dung khắc name_text bị gắn cờ bởi moderation NSFW. Nội dung khắc chỉ được kiểm duyệt cho nội dung NSFW — việc kiểm duyệt sở hữu trí tuệ chỉ áp dụng cho hình ảnh.
  • 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/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; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

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 một Keychain Build Task

Tạo huy hiệu móc khóa 3D có thể in cuối cùng từ một prototype task đã thành công. Quá trình build chạy một pipeline relief bản đồ độ sâu (depth-map) trên ảnh concept đã tô màu của prototype và trả về một artifact lưới duy nhất theo định dạng bạn yêu cầu. Tham khảo The Keychain Build Task Object để biết cấu trúc phản hồi.

Tham số

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

    Task ID của một prototype task đượ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 prototype task được tạo qua webapp không được chấp nhận — endpoint build chỉ chấp nhận các prototype task được tạo bởi POST /openapi/creative-lab/keychain/v1/prototype và từ chối mọi nguồn khác với mã 404.

  • Name
    name
    Type
    string
    Description

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

options

Các tham số điều chỉnh tùy chọn cho hình học relief. 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

    Hình dáng viền ngoài của huy hiệu 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 hình vuông bao quanh móc khóa, tính bằng milimet. Phạm vi: (0, 400].

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

    Chiều cao relief tối đa phía trên đế, tính bằng milimet. 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 (extrusion), tính bằng milimet. 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 relief, tính bằng milimet. Phạm vi: [0, 20].

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

    Xác định liệu mặt sau của huy hiệu có được bịt kín thành bề mặt đóng hay không. Đặt thành false để có vỏ hở.

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

    Đường cong chuyển đổi ánh xạ giá trị bản đồ độ sâu thành chiều cao relief. 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 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

    Cường độ làm mượt á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ố tỷ lệ dọc áp dụng thêm 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 lọc thấp cho các giá trị bản đồ độ sâu; bất kỳ giá trị nào dưới ngưỡng này sẽ bị kẹp về 0. Phạm vi: [0, 1].

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

    Tự động xóa nền của ảnh concept prototype trước khi tạo relief.

    Khác với tham số cùng tên của prototype (mặc định là false), tham số này kiểm soát việc chính ảnh prototype có được trả về với nền trong suốt hay không.

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

    Độ phân giải lưới dùng khi xuất. Phạm vi: [64, 2048].

output

Bộ chọn định dạng dữ liệu 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 tại model_urls.glb.
    • obj — nén model.obj + model.mtl + texture.png và trả về gói tại model_urls.obj.
    • zip — nén mọi artifact mà bộ tạo tạo ra và trả về gói tại model_urls.bundle_zip.

Giá trị trả về

Thuộc tính result của phản hồi chứa id task của keychain build task vừa được tạo. Hãy thăm dò (poll) endpoint Get a Task hoặc đăng ký stream cho đến khi task đạt trạng thái SUCCEEDED, sau đó tải artifact từ mục duy nhất trong model_urls.

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ệ.
    • Task cha chưa thành công: Prototype task được tham chiếu chưa đạt trạng thái SUCCEEDED.
    • Không có ứng viên: Prototype task đã thành công nhưng không tạo ra ảnh ứng viên nào.
    • Options nằm ngoài phạm vi: Một trong các trường của options nằm ngoài phạm vi cho phép hoặc tập giá trị enum.
  • 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

    Prototype task đượ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 prototype task chế độ API mới có thể nối tiếp 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/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 (prototype) hoặc tác vụ xây dựng (build) dựa trên 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ụ Nguyên mẫu Móc khóa và Đối tượng Tác vụ Xây dựng Móc khóa để biết hình dạng của phản hồi.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất của tác vụ móc khóa cần truy xuất.

Giá trị trả về

Phản hồi chứa đối tượng tác vụ móc khóa. Hình dạng của phản hồi 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 một Tác vụ Keychain

Hủy một tác vụ móc khóa. Nếu tác vụ vẫn đang ở trạng thái PENDING, số tín dụng đã tiêu tốn lúc 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 (do worker có thể đã đang sử dụng tài nguyên). Các tác vụ đã đạt 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ụ — thực hiện 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ụ móc khóa cần hủy.

Giá trị 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 thất bạ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/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 trực tiếp một tác vụ Keychain

Truyền trực tiếp các cập nhật theo thời gian thực cho một tác vụ móc khóa 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 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 lại.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất của tác vụ móc khóa cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng các đối tượng tác vụ Keychain Prototype hoặc Keychain Build dưới dạng Server-Sent Events. Mỗi khung dữ liệu mang theo toàn bộ đối tượng tác vụ cho giai đoạn đó — cùng cấu trúc mà endpoint Get trả về — vì vậy trong 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/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.
// 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-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)

List Keychain Tasks

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 duy nhất. Đường dẫn URL lựa 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 không được bao gồm trong bất kỳ phản hồi nào.

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. 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 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ụ build 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=***"
    ]
  }
]

The Keychain Prototype Task Object

Đối tượng Keychain Prototype Task 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 (concept image) đã tô màu từ một bức ảnh nguồn. Đầu ra của giai đoạn này được liên kết chuỗi 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 tác vụ. 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 tác vụ, 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 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. Là chuỗi rỗng nếu không có tên nào được cung cấp.

  • Name
    name_text
    Type
    string
    Description

    Nội dung khắc được áp dụng cho móc khóa này, sau khi cắt bỏ khoảng trắng và loại bỏ các ký tự định dạng vô hình. Không xuất hiện khi tác vụ được tạo mà không có name_text. So sánh giá trị này với những gì bạn đã gửi để xác nhận văn bản không bị thay đổi bởi việc mã hóa của HTTP client.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ. 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

    Tiến trình (progress) 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ụ đã hoàn thành 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.

    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, 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 tác vụ bắt đầu, tính bằng mili giây. Nếu tác 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 tác vụ kết thúc, tính bằng mili giây. Nếu tác vụ chưa kết thúc, 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 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 khi 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 đã 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 đối với các tác vụ 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 các ứng viên hình ảnh khái niệm được tạo bởi tác vụ 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 Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "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 Keychain Build Task Object

Đối tượng Keychain Build Task 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 prototype task đã thành công. Quá trình build sẽ chạy một pipeline relief bản đồ độ sâu trên ảnh khái niệm (concept image) của prototype và xuất bản một artifact lưới duy nhất theo đị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 của 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. 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 tác vụ. Các giá trị có thể có là một trong các giá trị 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, 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ụ 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ụ đứ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ố tín dụng đã tiêu thụ bởi tác vụ này. Trả về 0 đối với các tác vụ FAILED (tín dụng sẽ đượ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 đã được tạo ra, được đánh 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 này khớp với định dạng đã yêu cầu:

    • Name
      glb
      Type
      string
      Description

      URL có thể tải xuống cho tệp GLB. Xuất hiện 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. Xuất hiện khi output.format là obj.

    • Name
      bundle_zip
      Type
      string
      Description

      URL có thể tải xuống cho một gói zip chứa mọi artifact mà trình tạo xuất ra. Xuất hiện 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=***"
  }
}