lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

API Keycap của Creative Lab

Biến một bức ảnh thành một keycap tùy chỉnh đầy đủ màu sắc cho bàn phím cơ qua hai giai đoạn. Một tác vụ prototype sẽ tạo ra hình ảnh của keycap hoàn chỉnh từ bức ảnh. Một tác vụ build sẽ biến hình ảnh đó thành mô hình keycap 3D có texture. Nó lấy ID của tác vụ prototype làm input_task_id và ID ứng viên của hình ảnh làm candidate_id.

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

Cả hai endpoint POST đều yêu cầu gói trả phí. Một yêu cầu từ tài khoản gói miễn phí sẽ trả về 402.

POST/openapi/creative-lab/keycap/v1/prototype

Tạo tác vụ Keycap prototype

Tạo một hình ảnh keycap hoàn chỉnh từ một bức ảnh. Trường image_urls của tác vụ chứa hình ảnh, còn candidate_ids chứa ID của hình ảnh đó, mỗi trường có một mục. Nếu bạn không hài lòng với thiết kế, hãy tạo một tác vụ prototype khác. Meshy tính phí riêng cho mỗi tác vụ prototype.

Để tạo keycap 3D, hãy truyền ID của tác vụ này vào build endpoint dưới dạng input_task_id, cùng với mục candidate_ids dưới dạng candidate_id. Để biết các trường của tác vụ, xem Đối tượng tác vụ Keycap prototype.

Request

POST
/openapi/creative-lab/keycap/v1/prototype
# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/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": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

Tham số

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

    Bức ảnh để biến thành thiết kế keycap, dưới dạng URL công khai hoặc Data URI (data:image/jpeg;base64,<dữ liệu hình ảnh được mã hóa base64 của bạn>).

    Hình ảnh phải là tệp JPG, JPEG, PNG, hoặc WebP có dung lượng tối đa 20 MB (20.000.000 byte). Mỗi cạnh phải có kích thước tối thiểu 32 pixel, và hình ảnh có thể có tối đa 178.956.970 pixel. Một hình ảnh vượt quá các giới hạn này sẽ trả về 400.

    Meshy phát hiện định dạng từ dữ liệu hình ảnh, không phải từ phần mở rộng tệp trong URL. URL không có phần mở rộng vẫn hoạt động, và Meshy sẽ theo các chuyển hướng HTTP. Meshy áp dụng hướng xoay EXIF, vì vậy một bức ảnh chụp từ điện thoại bị xoay sẽ hiển thị đúng như hình ảnh thực tế.

    Data URI phải được mã hóa base64 với một kiểu hình ảnh, chẳng hạn như data:image/png;base64,..., và hình ảnh được giải mã phải là JPEG, PNG, hoặc WebP. Giới hạn 20 MB áp dụng cho hình ảnh đã giải mã, vì vậy văn bản base64 có thể lớn hơn khoảng một phần ba.

  • Name
    name
    Type
    string
    Description

    Tên cho tác vụ, tối đa 100 ký tự. Tên này sẽ xuất hiện trong trường name của tác vụ. Tên dài hơn sẽ trả về 400.

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

    Có xóa phông nền khỏi hình ảnh prototype hay không. true sẽ trả về một tệp PNG RGBA trong suốt, để bạn có thể đặt keycap lên bất kỳ nền nào. Nếu Meshy không thể xóa phông nền, nó sẽ trả về hình ảnh cùng với phông nền của nó, và tác vụ vẫn thành công.

    Thiết kế phần đầu mà quá trình build chuyển thành 3D vẫn giữ phông nền của nó dù trong trường hợp nào. Quá trình build sẽ vẽ phần đế keycap từ hình ảnh trong image_urls, không có phông nền nếu bạn đã gửi true. Quá trình build trả về hình ảnh đó dưới dạng process_image_urls.composite.

Giá trị trả về

Trường result chứa ID của tác vụ prototype mới. Lấy tác vụ hoặc truyền tác vụ dưới dạng luồng cho đến khi status là SUCCEEDED. Sau đó truyền ID vào build endpoint dưới dạng input_task_id, cùng với mục từ candidate_ids dưới dạng candidate_id.

Các chế độ thất bại

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể chạy. Ví dụ:

    • image_url bị thiếu.
    • Hình ảnh không phải là tệp JPG, JPEG, PNG, hoặc WebP.
    • Hình ảnh quá nhỏ, vượt quá 20 MB, hoặc vượt quá số pixel tối đa.
    • Meshy không thể tải hình ảnh xuống, chẳng hạn vì URL trả về 404 hoặc hết thời gian chờ.
    • Data URI không phải là base64 hợp lệ.
    • Hình ảnh bị gắn cờ là nội dung không phù hợp (NSFW).

    Thông báo lỗi cho biết vấn đề nào đã được phát hiện. Sửa yêu cầu, sau đó gửi lại.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Kiểm tra tiêu đề Authorization.

  • Name
    402 - Payment Required
    Description

    Một trong các trường hợp sau áp dụng:

    • Tài khoản không có đủ tín dụng.
    • Khóa API, không gian làm việc, hoặc thành viên đã đạt giới hạn tín dụng.
    • Tài khoản đang ở gói miễn phí.

    Kiểm tra tín dụng và gói của bạn, sau đó thử lại.

  • Name
    403 - Forbidden
    Description

    Nhóm của bạn đã bật tính năng Lọc IP, và Meshy đã gắn cờ hình ảnh vì vi phạm sở hữu trí tuệ của bên thứ ba. Hãy gửi một hình ảnh mà bạn có quyền sử dụng.

  • Name
    429 - Too Many Requests
    Description

    Một trong các giới hạn sau đã đạt tới:

    • Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Đợi vài giây, sau đó thử lại. Xem Giới hạn tốc độ.
    • Có quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Đợi một số tác vụ hoàn thành, sau đó thử lại.
    • Với gói không giới hạn nhưng không còn tín dụng, bạn đã đạt đến số lượng tác vụ có thể chạy mà không cần tín dụng. Đợi một tác vụ hoàn thành, hoặc nạp thêm tín dụng.
  • Name
    500 - Internal Server Error
    Description

    Meshy gặp lỗi máy chủ, chẳng hạn vì quá trình kiểm duyệt nội dung hoặc kiểm tra sở hữu trí tuệ không thể chạy, hoặc Meshy không thể lưu trữ hình ảnh. Meshy không tạo tác vụ, và hoàn lại bất kỳ khoản tín dụng nào đã bị tính phí. Hãy thử lại yêu cầu.

POST/openapi/creative-lab/keycap/v1/build

Tạo một tác vụ build Keycap

Tạo keycap 3D đã phủ texture từ một tác vụ prototype đã thành công và một trong các candidate của nó. Để biết các trường của nó, xem The Keycap build task object.

Một tác vụ build chạy qua mọi bước. Nó tạo ra một mô hình 3D từ bản thiết kế và tô màu cho nó. Sau đó, nó đặt và cắt mô hình lên phần đế keycap ở một tư thế mặc định đã được hiệu chỉnh, nên bạn không cần chỉnh tay. Cuối cùng, nó lắp ráp keycap và xuất các tệp. Một lần build thường mất từ 3 đến 7 phút.

Request

POST
/openapi/creative-lab/keycap/v1/build
# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}

Tham số

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

    ID của tác vụ prototype cần build. Nó phải là một tác vụ do tài khoản của bạn tạo bằng POST /openapi/creative-lab/keycap/v1/prototype, với trạng thái SUCCEEDED.

    Một ID không phải là một trong các tác vụ Keycap prototype của bạn từ API sẽ trả về 404, kể cả một prototype được tạo trong ứng dụng web.

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

    Candidate cần build, lấy từ mảng candidate_ids của tác vụ prototype. Một giá trị không nằm trong mảng đó sẽ trả về 400.

  • Name
    name
    Type
    string
    Description

    Tên cho tác vụ, tối đa 100 ký tự. Nó sẽ được trả về trong trường name của tác vụ. Một tên dài hơn sẽ trả về 400.

options

Các cài đặt hình học tùy chọn. Mỗi trường đều có một giá trị mặc định đã được hiệu chỉnh, vì vậy bạn chỉ cần gửi những trường mà bạn muốn thay đổi.

  • Name
    base_model
    Type
    string
    mặc định cherry-mx-1x1-r1
    Description

    Phần đế keycap để build lên. Giá trị duy nhất là cherry-mx-1x1-r1, một keycap profile Cherry MX 1u tiêu chuẩn. Kích thước tùy chỉnh không được hỗ trợ, và bất kỳ giá trị nào khác sẽ trả về 400.

  • Name
    head_size_mm
    Type
    number
    mặc định 23
    Description

    Kích thước của phần đầu (head) theo chiều dài nhất của nó, tính bằng milimét, từ 10 đến 40. Meshy sẽ co giãn phần đầu sao cho chiều dài nhất của nó khớp với giá trị này. Một giá trị ngoài phạm vi sẽ trả về 400.

    Với một giá trị trên khoảng 32.9, Meshy có thể giảm kích thước để phần đầu vừa với giới hạn phạm vi bảo vệ của đế. Khi đó phần đầu có thể nhỏ hơn so với yêu cầu của bạn. Đối tượng tác vụ không trả về kích thước mà Meshy đã áp dụng. Để kiểm tra, hãy đo hộp bao của lưới keycap-head trong mô hình.

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

    Độ dịch chuyển theo chiều dọc cần áp dụng cho phần đầu trước khi Meshy đặt nó lên đế, tính bằng milimét, từ -5 đến 5. Một giá trị ngoài phạm vi sẽ trả về 400.

Giá trị trả về

Trường result chứa ID của tác vụ build mới. Lấy tác vụ hoặc stream nó cho đến khi status là SUCCEEDED. Sau đó tải tệp GLB từ model_urls.glb và gói OBJ từ model_urls.obj_zip.

Meshy xuất tệp GLB và gói OBJ theo tỷ lệ thực tế tính bằng milimét. Cả hai đều sử dụng hệ tọa độ Y-up, với mặt trước của keycap hướng về +Z.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể chạy. Ví dụ:

    • input_task_id bị thiếu hoặc không phải là một ID tác vụ hợp lệ.
    • Trạng thái của tác vụ prototype không phải là SUCCEEDED. Nếu nó vẫn đang chạy, hãy đợi và thử lại. Nếu nó thất bại hoặc bị hủy, hãy tạo một tác vụ prototype mới.
    • Tác vụ prototype đã thành công nhưng không có candidate nào. Hãy tạo một tác vụ prototype mới.
    • candidate_id bị thiếu, hoặc không nằm trong candidate_ids của tác vụ prototype. Hãy gửi một giá trị từ mảng đó.
    • Một trường trong options nằm ngoài phạm vi, hoặc base_model không phải là một giá trị khả dụng.

    Thông báo lỗi sẽ cho biết vấn đề nào đã được phát hiện.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra tiêu đề Authorization.

  • Name
    402 - Payment Required
    Description

    Một trong các trường hợp sau áp dụng:

    • Tài khoản không có đủ tín dụng.
    • Khóa API, không gian làm việc, hoặc thành viên đã đạt đến giới hạn tín dụng của mình.
    • Tài khoản đang ở gói miễn phí.

    Hãy kiểm tra tín dụng và gói của bạn, sau đó thử lại.

  • Name
    404 - Not Found
    Description

    input_task_id không khớp với bất kỳ tác vụ Keycap prototype nào mà tài khoản của bạn đã tạo bằng API. Một prototype được tạo trong ứng dụng web cũng sẽ trả về 404. Hãy gửi ID result từ một phản hồi tạo prototype.

  • Name
    429 - Too Many Requests
    Description

    Một trong các giới hạn sau đã đạt tới:

    • Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Hãy đợi vài giây, rồi thử lại. Xem Rate limits.
    • Có quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Hãy đợi một số tác vụ hoàn thành, rồi thử lại.
    • Trên một gói không giới hạn nhưng không còn tín dụng, bạn đã đạt đến số lượng tác vụ có thể chạy mà không cần tín dụng. Hãy đợi một tác vụ hoàn thành, hoặc nạp thêm tín dụng.
  • Name
    500 - Internal Server Error
    Description

    Meshy không thể tạo tác vụ do lỗi máy chủ. Meshy sẽ hoàn lại bất kỳ khoản tín dụng nào đã bị trừ. Hãy thử lại yêu cầu.

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

Lấy tác vụ Keycap

Trả về một tác vụ prototype hoặc build. Đường dẫn phải khớp với giai đoạn của tác vụ. Một tác vụ build được yêu cầu thông qua /prototype/:id sẽ trả về 404, và một tác vụ prototype được yêu cầu thông qua /build/:id cũng vậy.

Để biết các trường, xem The Keycap prototype task object và The Keycap build task object.

Request

GET
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo.

Giá trị trả về

Đối tượng tác vụ prototype hoặc đối tượng tác vụ build, tương ứng với giai đoạn trong đường dẫn.

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

  • Name
    400 - Bad Request
    Description

    id không phải là một ID tác vụ hợp lệ. Hãy gửi ID result từ phản hồi tạo.

  • Name
    403 - Forbidden
    Description

    Nhóm của bạn đã bật IP Filtering, và Meshy đã gắn cờ hình ảnh của tác vụ prototype vì vi phạm sở hữu trí tuệ của bên thứ ba. Các tác vụ build và các nhóm thuộc gói Enterprise sẽ không gặp lỗi này. Hãy tạo một tác vụ prototype từ hình ảnh mà bạn có quyền sử dụng.

  • Name
    404 - Not Found
    Description

    Không có tác vụ Keycap nào với ID này thuộc về tài khoản của bạn, hoặc giai đoạn của tác vụ không khớp với đường dẫn. Hãy kiểm tra lại ID, và sử dụng /prototype hoặc /build cho phù hợp với tác vụ.

  • Name
    500 - Internal Server Error
    Description

    Meshy không thể chạy kiểm tra sở hữu trí tuệ. Hãy thử lại yêu cầu.

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

Xóa một tác vụ Keycap

Hủy một tác vụ Keycap. Hủy một tác vụ PENDING sẽ hoàn lại tín dụng của tác vụ đó. Một tác vụ IN_PROGRESS sẽ bị hủy mà không được hoàn tiền, vì một worker đã bắt đầu xử lý nó. Một tác vụ có trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) không thể bị hủy.

Đường dẫn phải khớp với giai đoạn của tác vụ. Ví dụ, gọi DELETE trên /prototype/:id với ID của một tác vụ build sẽ trả về 404.

Request

DELETE
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

Tham số đường dẫn

  • Name
    id
    Type
    path
    Description

    ID của tác vụ cần hủy.

Giá trị trả về

204 No Content với nội dung rỗng.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Một trong những trường hợp sau áp dụng:

    • id không phải là một ID tác vụ hợp lệ. Hãy gửi ID result từ phản hồi tạo tác vụ.
    • Tác vụ đã có trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED), nên không thể bị hủy.
  • Name
    404 - Not Found
    Description

    Không có tác vụ Keycap nào với ID này thuộc về tài khoản của bạn, hoặc giai đoạn của tác vụ không khớp với đường dẫn. Hãy kiểm tra ID, và sử dụng /prototype hoặc /build để khớp với tác vụ.

  • Name
    500 - Internal Server Error
    Description

    Meshy gặp lỗi máy chủ khi hủy tác vụ, vì vậy tác vụ có thể đã bị hủy hoặc chưa. Hãy lấy thông tin tác vụ để kiểm tra status của nó trước khi thử lại.

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

Stream a Keycap task

Phát trực tuyến các cập nhật của một tác vụ Keycap dưới dạng Server-Sent Events (SSE). Đường dẫn phải khớp với giai đoạn của tác vụ. Nếu không khớp, ví dụ như ID của một tác vụ build được dùng tại /prototype/:id/stream, luồng sẽ gửi một sự kiện error với status_code: 404 rồi đóng lại.

Request

GET
/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/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 following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***"
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo (create response).

Giá trị trả về

Một luồng các đối tượng tác vụ prototype hoặc build. Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, giống như những gì Lấy thông tin một tác vụ Keycap trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra vẫn còn trống (null, [], hoặc {}), và finished_at là null.

Nếu IP Filtering chặn kết quả của tác vụ, luồng sẽ gửi một sự kiện error thay thế, kèm theo status_code mà một yêu cầu get sẽ trả về.

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

List Keycap tasks

Trả về các tác vụ Keycap của bạn thuộc một giai đoạn, mỗi lần một trang. Đường dẫn sẽ chọn giai đoạn. /prototype chỉ trả về các tác vụ prototype, và /build chỉ trả về các tác vụ build.

Request

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

Tham số đường dẫn

  • Name
    stage
    Type
    path
    Bắt buộc
    Description

    Giai đoạn cần liệt kê, prototype hoặc build.

Tham số truy vấn

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

    Trang cần trả về, từ 1 đến 255. 0 sẽ trả về trang đầu tiên. Giá trị ngoài khoảng 0 đến 255 sẽ trả về 400.

  • Name
    page_size
    Type
    integer
    mặc định 10
    Description

    Số lượng tác vụ trên mỗi trang, tối đa 100. Giá trị từ 101 đến 255 sẽ trả về 100 tác vụ, và 0 sẽ sử dụng giá trị mặc định. Giá trị ngoài khoảng 0 đến 255 sẽ trả về 400.

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

    Thứ tự sắp xếp.

    Các giá trị khả dụng:

    • -created_at: mới nhất trước
    • +created_at: cũ nhất trước

Giá trị trả về

Một mảng các đối tượng tác vụ prototype hoặc đối tượng tác vụ build, tương ứng với giai đoạn trong đường dẫn.

Đối tượng tác vụ prototype Keycap

Một tác vụ prototype tạo ra một hình ảnh của chiếc keycap hoàn thiện từ một bức ảnh. Để biến thiết kế thành một chiếc keycap 3D, hãy truyền ID của tác vụ đến build endpoint dưới dạng input_task_id, cùng với mục candidate_ids của nó dưới dạng candidate_id.

Thuộc tính

Example Keycap Prototype Task Object

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}
  • Name
    id
    Type
    string
    Description

    ID của tác vụ. Đừng phụ thuộc vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại tác vụ, luôn là creative-lab-keycap-prototype.

  • Name
    name
    Type
    string
    Description

    name mà bạn đã gửi khi tạo tác vụ, hoặc "" nếu bạn không gửi.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ.

    Các giá trị khả dụng:

    • PENDING: đang chờ trong hàng đợi
    • IN_PROGRESS: đang tạo kết quả
    • SUCCEEDED: trạng thái cuối, kèm kết quả
    • FAILED: trạng thái cuối, kèm lý do trong task_error
    • CANCELED: trạng thái cuối, không có kết quả
  • Name
    progress
    Type
    integer
    Description

    Phần trăm công việc đã hoàn thành, từ 0 đến 100. Giá trị này là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.

  • Name
    created_at
    Type
    timestamp
    Description

    Thời điểm tác vụ được tạo, tính bằng mili-giây Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Thời điểm một worker bắt đầu tác vụ, tính bằng mili-giây Unix. Giá trị là null cho đến lúc đó.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm tác vụ đạt trạng thái cuối, tính bằng mili-giây Unix. Giá trị là null cho đến lúc đó.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm kết quả của tác vụ hết hạn, tính bằng mili-giây Unix. Thời điểm này là 3 ngày sau finished_at, hoặc 3 ngày sau created_at cho đến khi tác vụ hoàn tất. Đối với tài khoản Doanh nghiệp, vốn giữ kết quả API vô thời hạn, thời điểm này là khoảng 100 năm sau. Xem Lưu giữ tài nguyên.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Vị trí của tác vụ trong hàng đợi khi nó đang ở trạng thái PENDING. 1 nghĩa là nó sẽ bắt đầu tiếp theo. Giá trị là 0 sau khi tác vụ rời khỏi hàng đợi, và luôn là 0 trong kết quả danh sách.

  • Name
    task_error
    Type
    object
    Description

    Lý do tác vụ thất bại. Giá trị là null trừ khi status là FAILED. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng bị tính phí cho tác vụ, sau khi đã hoàn tiền (nếu có). Một yêu cầu trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại có giá trị 0, vì Meshy sẽ hoàn lại tín dụng. Việc hủy chỉ hoàn tiền cho tác vụ khi tác vụ đang ở trạng thái PENDING. Nếu Meshy không thể đọc được khoản phí, phản hồi get hoặc stream sẽ bỏ qua trường này, và một yêu cầu danh sách sẽ trả về 500. Trong trường hợp đó, hãy thử lại yêu cầu.

  • Name
    image_urls
    Type
    array of strings
    Description

    URL tải xuống cho hình ảnh của chiếc keycap hoàn thiện. Mảng này có một URL sau khi tác vụ thành công, và trống cho đến lúc đó. image_urls[i] hiển thị ứng viên trong candidate_ids[i].

    Các URL này dùng để hiển thị. Build endpoint lấy một mục từ candidate_ids, không phải một URL. Đây là các URL đã được ký, vì vậy hãy lấy chúng mà không cần header Authorization. Chúng vẫn có hiệu lực cho đến expires_at, và việc lấy lại tác vụ sẽ trả về cùng các URL đó.

  • Name
    candidate_ids
    Type
    array of strings
    Description

    ID của các ứng viên, theo cùng thứ tự với image_urls. Để build một ứng viên, hãy gửi ID của nó dưới dạng candidate_id trong yêu cầu build. Đừng phụ thuộc vào định dạng của các ID này.

Đối tượng tác vụ xây dựng Keycap

Một tác vụ xây dựng tạo ra chiếc keycap 3D có texture từ một tác vụ tạo mẫu đã thành công và một trong các ứng viên của nó. Nó tạo mô hình 3D, tô màu cho mô hình, lắp và cắt mô hình vào đế keycap, sau đó lắp ráp và xuất keycap.

Thuộc tính

Example Keycap Build Task Object

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

    ID của tác vụ. Đừng dựa vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại tác vụ, luôn là creative-lab-keycap-build.

  • Name
    name
    Type
    string
    Description

    name mà bạn đã gửi khi tạo tác vụ, hoặc "" nếu bạn không gửi.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ.

    Các giá trị khả dụng:

    • PENDING: đang chờ trong hàng đợi
    • IN_PROGRESS: đang tạo kết quả
    • SUCCEEDED: trạng thái cuối cùng, có kết quả
    • FAILED: trạng thái cuối cùng, với lý do trong task_error
    • CANCELED: trạng thái cuối cùng, không có kết quả
  • Name
    progress
    Type
    integer
    Description

    Phần trăm công việc đã hoàn thành, từ 0 đến 100. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.

  • Name
    created_at
    Type
    timestamp
    Description

    Thời điểm tác vụ được tạo, tính bằng mili giây Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Thời điểm một worker bắt đầu tác vụ, tính bằng mili giây Unix. null cho đến khi đó.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm tác vụ đạt đến trạng thái cuối cùng, tính bằng mili giây Unix. null cho đến khi đó.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm kết quả của tác vụ hết hạn, tính bằng mili giây Unix. Đó là 3 ngày sau finished_at, hoặc 3 ngày sau created_at cho đến khi tác vụ hoàn thành. Đối với các tài khoản Enterprise, vốn giữ kết quả API vô thời hạn, đó là khoảng 100 năm sau. Xem Lưu giữ tài nguyên.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Vị trí của tác vụ trong hàng đợi khi nó đang ở trạng thái PENDING. 1 nghĩa là nó sẽ bắt đầu kế tiếp. 0 sau khi tác vụ rời khỏi hàng đợi, và luôn là 0 trong kết quả danh sách.

  • Name
    task_error
    Type
    object
    Description

    Lý do tác vụ thất bại. null trừ khi status là FAILED. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng bị tính phí cho tác vụ, sau khi hoàn tiền (nếu có). Một yêu cầu trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại có giá trị 0, vì Meshy sẽ hoàn lại tín dụng. Việc hủy chỉ hoàn tín dụng cho một tác vụ khi nó đang ở trạng thái PENDING. Nếu Meshy không thể đọc được khoản phí, phản hồi get hoặc stream sẽ bỏ qua trường này, và một yêu cầu danh sách sẽ trả về 500. Trong trường hợp đó, hãy thử lại yêu cầu.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống cho mô hình 3D. Meshy xuất file GLB và gói OBJ theo tỷ lệ thực tế tính bằng milimét, trục Y hướng lên, với mặt trước của keycap hướng về +Z.

    Mô hình có các lưới tên là keycap-head và keycap-base. Khi Meshy sử dụng phương án dự phòng là tô một họa tiết cho đế, mô hình cũng sẽ có một lưới keycap-base-interior cho khoang trụ (stem cavity). Đừng giả định rằng mô hình chỉ có đúng hai lưới.

    Đây là các URL đã được ký, vì vậy hãy tải chúng xuống mà không cần header Authorization. Chúng vẫn còn hiệu lực cho đến expires_at, và việc lấy lại tác vụ trước thời điểm đó sẽ trả về cùng các URL. Một URL đã hết hạn không thể được gia hạn, vì vậy hãy tải xuống và lưu trữ các file trước thời điểm đó.

    • Name
      glb
      Type
      string
      Description

      URL tải xuống cho file GLB có texture, model.glb.

    • Name
      obj_zip
      Type
      string
      Description

      URL tải xuống cho gói OBJ, một file ZIP chứa model.obj, model.mtl, và các texture PNG mà model.mtl sử dụng. Với đế có màu đơn sắc, texture duy nhất là keycap-head.png. Với đế có họa tiết, file ZIP cũng có keycap-base.png.

  • Name
    process_image_urls
    Type
    object
    Description

    URL tải xuống cho các hình ảnh từ các bước xây dựng, được đánh khóa theo loại. Giống như model_urls, đây là các URL đã được ký, vì vậy hãy tải chúng xuống mà không cần header Authorization. Chúng vẫn còn hiệu lực cho đến expires_at, và việc lấy lại tác vụ sẽ trả về cùng các URL.

    Nó có thể có các khóa sau:

    • head_design: hình ảnh thiết kế của ứng viên được chọn, mà quá trình xây dựng đã chuyển thành 3D. Luôn có mặt.
    • composite: hình ảnh của chiếc keycap hoàn thiện cho ứng viên được chọn, mà quá trình xây dựng đã dùng để tô màu đế. Có thể bị thiếu.
    • base_canvas: đế keycap đã được tô màu. Có thể bị thiếu.

    Meshy có thể bổ sung thêm các khóa, vì vậy hãy bỏ qua bất kỳ khóa nào bạn không nhận ra.

Ví dụ đầu cuối

Ví dụ này chạy toàn bộ luồng:

  1. Tạo một tác vụ prototype từ một bức ảnh.
  2. Lấy tác vụ cho đến khi status của nó là SUCCEEDED.
  3. Chọn một ứng viên từ candidate_ids.
  4. Tạo một tác vụ build với ứng viên đó.
  5. Lấy tác vụ build cho đến khi status của nó là SUCCEEDED.
  6. Tải xuống tệp GLB và gói OBJ từ model_urls.

Ví dụ này chọn ứng viên đầu tiên. Trong ứng dụng của bạn, hãy hiển thị các mục image_urls cho người dùng và để họ chọn. Chỉ số của một hình ảnh được chọn trong image_urls chính là chỉ số của ID của nó trong candidate_ids.

Complete flow

POST
/openapi/creative-lab/keycap/v1
#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi

BASE="https://api.meshy.ai/openapi/creative-lab/keycap/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"image_url":"data:%s;base64,' "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  printf '{"image_url":"%s"}' "$IMAGE_URL" >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the design render
poll prototype "$PROTO_ID"

# 3. Pick a candidate (first one here; show image_urls to a user in production)
CANDIDATE_ID=$(api GET "$BASE/prototype/$PROTO_ID" | jq -r '.candidate_ids[0]')

# 4. Create the build task
jq -n --arg p "$PROTO_ID" --arg c "$CANDIDATE_ID" \
  '{input_task_id: $p, candidate_id: $c}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 5. Wait for the model (a build usually takes 3-7 minutes)
poll build "$BUILD_ID"

# 6. Download the artifacts. These are signed URLs: no Authorization header,
#    and they stay valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o keycap.glb "$(jq -r '.model_urls.glb' <<<"$TASK")"
curl --silent --show-error --fail --max-time 900 \
  -o keycap-obj.zip "$(jq -r '.model_urls.obj_zip' <<<"$TASK")"
echo "Done: keycap.glb + keycap-obj.zip"