Creative Lab — Keycap API

Biến một bức ảnh nguồn thành một keycap bàn phím cơ tùy chỉnh đầy màu sắc qua hai giai đoạn: nguyên mẫu tạo ra một bản thiết kế "keycap hoàn chỉnh" từ bức ảnh đầu vào của bạn. Khi bạn đã xác nhận bản thiết kế đó, xây dựng sẽ biến nó thành một mô hình keycap 3D có kết cấu trong một lần chạy duy nhất — tạo mô hình trắng, tự động đặt và cắt trên một tư thế mặc định đã được hiệu chỉnh, tô màu mô hình đầy đủ và lắp ráp cuối cùng đều diễn ra trong một nhiệm vụ xây dựng. Hai giai đoạn này được liên kết thông qua input_task_id cộng với 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 một gói đăng ký trả phí. Các yêu cầu từ tài khoản gói miễn phí sẽ bị từ chối với 402 Payment Required.

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

Tạo Nhiệm Vụ Nguyên Mẫu Keycap

Tạo một bản render thiết kế keycap hoàn chỉnh từ ảnh nguồn. Kết quả của nhiệm vụ chứa một mảng image_urls (bản render hiển thị của keycap hoàn chỉnh) và một mảng candidate_ids song song; cả hai đều chứa một mục. Gọi lại endpoint này để có bản render khác nếu kết quả không như mong muốn — mỗi lần gọi sẽ được tính phí riêng. Truyền candidate_id cùng với ID nhiệm vụ nguyên mẫu đến endpoint xây dựng. Tham khảo Đối Tượng Nhiệm Vụ Nguyên Mẫu Keycap để 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 chuyển thành hình ảnh thiết kế keycap. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Định dạng được phát hiện bằng cách giải mã dữ liệu hình ảnh, không phải từ phần mở rộng tệp của URL — một URL không có phần mở rộng, hoặc một URL chuyển hướng, vẫn hoạt động miễn là các byte giải mã thành định dạng được hỗ trợ. Các chuyển hướng HTTP được theo dõi. Hướng EXIF được chuẩn hóa, vì vậy một bức ảnh điện thoại bị xoay sẽ được sử dụng theo cách nó hiển thị.
Giới hạn: ít nhất 32 pixel mỗi cạnh, tối đa 178,956,970 pixel tổng cộng, và tối đa 20,000,000 byte sau khi tải xuống. Đối với một Data URI, giới hạn áp dụng cho các byte đã giải mã, vì vậy tệp nguồn có thể có kích thước tối đa đó — văn bản base64 lớn hơn khoảng một phần ba, điều này quan trọng đối với nội dung yêu cầu của bạn, không phải đối với giới hạn này. Một Data URI phải khai báo loại nội dung image/* và ;base64.
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: 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 cho mục đích hiển thị. Tối đa 100 ký tự.
Name
remove_background
Type
boolean
mặc định false
Description
Khi được đặt thành true, bản render hiển thị trả về trong image_urls là một PNG RGBA trong suốt với nền đã được loại bỏ, vì vậy bạn có thể ghép nó lên bất kỳ nền nào.
Điều này chỉ áp dụng cho bản render hiển thị. Ứng viên mà endpoint xây dựng tiêu thụ không bị ảnh hưởng, vì vậy kết quả 3D là giống nhau dù thế nào.

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 keycap mới được tạo. Kiểm tra endpoint Lấy Nhiệm Vụ hoặc đăng ký luồng cho đến khi nhiệm vụ đạt SUCCEEDED, sau đó lấy mục từ candidate_ids và truyền nó, cùng với ID nhiệm vụ, đến endpoint xây dựng.

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ị 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.
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
Tài khoản đang ở gói miễn phí (cần gói trả phí để tạo nhiệm vụ) hoặc không đủ tín dụng.
Name
403 - Forbidden
Description
Hình ảnh đầu vào bị gắn cờ bởi moderation sở hữu trí tuệ.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.
Name
500 - Internal Server Error
Description
Một lỗi không mong muốn từ phía máy chủ đã xảy ra — ví dụ như dịch vụ moderation nội dung không khả dụng, không thể dàn dựng hình ảnh đầu vào, hoặc không thể tạo nhiệm vụ. Không có nhiệm vụ nào được tạo trong trường hợp này, vì vậy thử lại là an toàn.

Yêu Cầu

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

Phản Hồi

{
  "result": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

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

Tạo một Nhiệm Vụ Xây Dựng Keycap

Tạo mô hình keycap 3D có dán 3D texture cuối cùng từ một nhiệm vụ nguyên mẫu đã thành công và một trong những ứng viên của nó. Một nhiệm vụ xây dựng duy nhất chạy toàn bộ quy trình từ đầu đến cuối — tạo mô hình trắng từ thiết kế đã chọn, tự động đặt và cắt lên đế keycap bằng tư thế mặc định đã được hiệu chỉnh (không cần điều chỉnh tương tác), tô màu mô hình đầy đủ, và lắp ráp cuối cùng và xuất. Một lần xây dựng thường mất 3–7 phút, gần mức cao nhất khi nhiều lần xây dựng chạy đồng thời. Tham khảo Đối Tượng Nhiệm Vụ Xây Dựng Keycap để biết hình dạng 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 bởi cùng một tài khoản Meshy, phải đã đạt SUCCEEDED, và phải đã tạo ra ít nhất một ứ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 các nhiệm vụ nguyên mẫu được tạo bởi POST /openapi/creative-lab/keycap/v1/prototype và từ chối bất kỳ nguồn nào khác với 404.
Name
candidate_id
Type
string
Bắt buộc
Description
Ứng viên để xây dựng, được lấy từ mảng candidate_ids của nhiệm vụ nguyên mẫu đã thành công. Phải thuộc về nhiệm vụ đó; bất kỳ giá trị nào khác sẽ bị từ chối với 400.
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`

Tùy chỉnh hình học tùy chọn. Mỗi trường có một giá trị mặc định đã được hiệu chỉnh — chỉ gửi những trường bạn muốn ghi đè.

Name
base_model
Type
string
mặc định cherry-mx-1x1-r1
Description
Đế keycap để xây dựng. Hiện tại, giá trị duy nhất có sẵn là cherry-mx-1x1-r1 — một keycap 1u chuẩn Cherry MX profile. 3–5 kích thước tiêu chuẩn chính thống bổ sung đang được lên kế hoạch; kích thước tùy chỉnh không được hỗ trợ.
Name
head_size_mm
Type
number
mặc định 23
Description
Kích thước mục tiêu của đầu điêu khắc, tính bằng milimét: kích thước dài nhất của nó được tỷ lệ hóa thành giá trị này. Phạm vi: [10, 40]. Các giá trị trên khoảng 32.9 có thể bị giảm để đầu vẫn phù hợp với giới hạn dấu chân bảo vệ của đế, do đó kích thước dài nhất được cung cấp có thể nhỏ hơn yêu cầu. Giá trị áp dụng không được phản hồi lại trên đối tượng nhiệm vụ hôm nay — nếu bạn cần xác nhận kích thước bạn thực sự nhận được, hãy đo hộp bao của lưới keycap-head trong mô hình đã tải xuống.
Name
vertical_offset_mm
Type
number
mặc định 0
Description
Độ lệch dọc được áp dụng cho đầu trước khi nó được đặt trên đế, tính bằng milimét. Phạm vi: [-5, 5].

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 keycap 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 SUCCEEDED, sau đó tải xuống các hiện vật từ model_urls.glb và model_urls.obj_zip.

Cả gói GLB và OBJ đều được xuất ở tỷ lệ milimét thực tế, với hệ tọa độ Y-up và mặt trước của keycap hướng về +Z.

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ố: input_task_id và candidate_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ệ.
- Cha chưa thành công: Nhiệm vụ nguyên mẫu được tham chiếu chưa đạt 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 ứng viên nào.
- Ứng viên không xác định: candidate_id không phải là một trong những ứng viên của nhiệm vụ đầu vào.
- 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
Tài khoản đang ở gói miễn phí (cần gói trả phí để tạo nhiệm vụ) hoặc không đủ tín dụng.
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 chuỗi vào 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.
Name
500 - Internal Server Error
Description
Một lỗi không mong muốn từ phía máy chủ đã xảy ra — ví dụ như dịch vụ kiểm duyệt nội dung không khả dụng, dàn dựng hình ảnh đầu vào thất bại, hoặc nhiệm vụ không thể được tạo. Không có nhiệm vụ nào được tạo trong trường hợp này, vì vậy thử lại là an toàn.

Yêu cầu

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

Phản hồi

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

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

Truy xuất Nhiệm vụ Keycap

Truy xuất một nhiệm vụ prototype hoặc build 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ụ build đượ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ụ Prototype Keycap và Đối tượng Nhiệm vụ Build Keycap để 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ụ keycap cần truy xuất.

Trả về

Phản hồi chứa đối tượng nhiệm vụ keycap. 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/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}"

Phản hồi Prototype

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

Phản hồi Build

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

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

Xóa một Nhiệm vụ Keycap

Hủy một nhiệm vụ keycap. 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 trả. Các nhiệm vụ đã IN_PROGRESS sẽ bị hủy mà không hoàn trả (người thực hiệ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ụ keycap cần hủy.

Trả về

Trả về 204 No Content khi thành công với nội dung trố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.
Name
500 - Internal Server Error
Description
Một lỗi không mong muốn từ phía máy chủ xảy ra khi hủy. Nhiệm vụ có thể đã hoặc chưa bị hủy — đọc lại để xác nhận trước khi thử lại.

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).

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

Truyền tải một Nhiệm vụ Keycap

Truyền tải cập nhật thời gian thực cho một nhiệm vụ keycap 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ụ keycap để truyền tải.

Trả về

Trả về một luồng các đối tượng nhiệm vụ Keycap Prototype hoặc Keycap 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.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

Danh sách Nhiệm vụ Keycap

Lấy danh sách phân trang các nhiệm vụ keycap 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. 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 — việc 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à 100 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 keycap khi liệt kê /prototype hoặc đối tượng nhiệm vụ xây dựng keycap khi liệt kê /build.

Yêu cầu

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

Phản hồi (Danh sách Nhiệm vụ Nguyên mẫu)

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

Đối tượng Nhiệm vụ Nguyên mẫu Keycap

Đối tượng Nhiệm vụ Nguyên mẫu Keycap là một đơn vị công việc mà Meshy theo dõi để tạo ra một hình ảnh thiết kế keycap hoàn chỉnh từ một bức ảnh nguồn. Kết quả 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 cộng với candidate_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 theo 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 của nhiệm vụ. Giá trị là creative-lab-keycap-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ụ 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ụ 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ố tín dụng tiêu thụ bởi nhiệm vụ này. Một nhiệm vụ đạt SUCCEEDED sẽ bị tính phí đầy đủ cho giai đoạn của nó. Một nhiệm vụ không bao giờ được tạo (một 4xx tại thời điểm yêu cầu, bao gồm cả từ chối kiểm duyệt) sẽ không bị tính phí. Một nhiệm vụ đạt FAILED trả về 0 — phí được hoàn lại, bao gồm cả chặn kiểm duyệt không đồng bộ. Hủy qua DELETE chỉ hoàn lại khi nhiệm vụ vẫn còn PENDING; một nhiệm vụ đã IN_PROGRESS vẫn bị tính phí, vì công việc đã được thực hiện.
Name
image_urls
Type
array of strings
Description
URL có thể tải xuống của bản render thiết kế keycap hoàn chỉnh — những gì ứng viên trông như một keycap hoàn chỉnh. Chứa một mục duy nhất; image_urls[i] tương ứng với candidate_ids[i]. Trống cho đến khi nhiệm vụ đạt SUCCEEDED. URL chỉ để hiển thị; endpoint xây dựng tiêu thụ candidate_ids, không phải các URL này. Vòng đời URL giống như model_urls: có chữ ký, không có tiêu đề Authorization, hợp lệ cho đến expires_at, và ổn định khi nhiệm vụ được đọc lại.
Name
candidate_ids
Type
array of strings
Description
Định danh ứng viên không rõ ràng, song song với image_urls. Chuyển mục phù hợp với thiết kế bạn chọn làm candidate_id của yêu cầu xây dựng. Không đưa ra bất kỳ giả định nào về định dạng của các id này.

Ví dụ về Đối tượng Nhiệm vụ Nguyên mẫu Keycap

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

Đối tượng Nhiệm vụ Xây dựng Keycap

Đối tượng Nhiệm vụ Xây dựng Keycap là một đơn vị công việc mà Meshy theo dõi để tạo ra keycap 3D có texture cuối cùng từ một nhiệm vụ nguyên mẫu thành công và một ứng viên được chọn. Một lần xây dựng chạy toàn bộ quy trình — tạo mô hình trắng, tự động lắp đặt và cắt, tô màu, lắp ráp và xuất khẩu.

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho nhiệm vụ.
Name
type
Type
string
Description
Loại nhiệm vụ. Giá trị là creative-lab-keycap-build.
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.
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.
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.
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 đó. 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 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. Một nhiệm vụ đạt SUCCEEDED sẽ bị tính phí toàn bộ cho giai đoạn của nó. Một nhiệm vụ không bao giờ được tạo (một 4xx tại thời điểm yêu cầu, bao gồm cả từ chối kiểm duyệt) sẽ không bị tính phí. Một nhiệm vụ đạt FAILED trả về 0 — phí được hoàn lại, bao gồm cả chặn kiểm duyệt không đồng bộ. Hủy qua DELETE chỉ hoàn lại khi nhiệm vụ vẫn còn PENDING; một nhiệm vụ đã IN_PROGRESS vẫn bị tính phí, vì công việc đã được thực hiện.
Name
model_urls
Type
object
Description
URL có thể tải xuống cho các tài sản mô hình đã tạo. Cả gói GLB và OBJ đều được xuất ở tỷ lệ milimet thực tế, Y-up, với mặt trước của keycap hướng +Z. Các lưới được đặt tên là keycap-head và keycap-base; khi phần đế quay lại một mẫu điền, một lưới thứ ba keycap-base-interior cũng có mặt cho khoang thân. Không giả định chính xác hai lưới.
Đây là các URL đã ký: tải chúng không có tiêu đề Authorization. Chúng vẫn hợp lệ cho đến expires_at, là 3 ngày sau finished_at, và đọc lại nhiệm vụ trong khoảng thời gian đó trả về URL giống hệt thay vì một URL mới được ký. Tải xuống và lưu trữ các tệp trước đó — không có cách nào để làm mới một liên kết đã hết hạn.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống cho model.glb có texture cuối cùng.
- Name
  obj_zip
  Type
  string
  Description
  URL có thể tải xuống cho một gói zip chứa model.obj, model.mtl, và các PNG texture mà MTL của nó thực sự tham chiếu. Một phần đế màu đồng nhất chỉ cung cấp keycap-head.png; một phần đế có hoa văn cũng cung cấp keycap-base.png.
Name
process_image_urls
Type
object
Description
URL có thể tải xuống cho các hình ảnh quy trình trung gian, được khóa theo loại. Chu kỳ URL giống như model_urls: đã ký, không có tiêu đề Authorization, hợp lệ cho đến expires_at, và ổn định khi nhiệm vụ được đọc lại. Các loại hiện tại được phát ra:
- head_design — hình ảnh thiết kế của ứng viên được chọn mà quá trình xây dựng đã tiêu thụ (luôn có mặt).
- composite — kết xuất hiển thị keycap hoàn thành của ứng viên được chọn (có mặt khi có sẵn).
- base_canvas — canvas phần đế keycap đã được sơn (có mặt khi có sẵn).
Xem tập hợp khóa như mở rộng; các loại mới có thể được thêm vào mà không cần thay đổi phá vỡ.

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

Ví dụ Từ Đầu Đến Cuối

Quy trình hoàn chỉnh: tạo một nguyên mẫu từ một bức ảnh, kiểm tra nó đến SUCCEEDED, chọn một ứng viên từ candidate_ids, tạo một bản dựng với ứng viên đó, kiểm tra bản dựng đến SUCCEEDED, sau đó tải xuống gói GLB và OBJ từ model_urls.

Ví dụ chọn ứng viên đầu tiên một cách lập trình. Trong một tích hợp thực tế, bạn sẽ hiển thị mục image_urls cho người dùng cuối và để họ chọn; chỉ số được chọn ánh xạ 1:1 với candidate_ids.

Quy trình hoàn chỉnh

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"