Creative Lab Keychain API

Biến một bức ảnh thành móc khóa có thể in 3D với phần nổi màu qua hai giai đoạn. Một tác vụ tạo mẫu sẽ tạo ra hình ảnh ý tưởng có màu từ bức ảnh. Một tác vụ dựng mô hình sẽ biến hình ảnh đó thành mô hình 3D nổi, và sử dụng ID của tác vụ tạo mẫu làm 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 ra một ảnh khái niệm được tô màu từ một bức ảnh. Để xây dựng mô hình 3D, hãy truyền ID của tác vụ này vào endpoint build dưới dạng input_task_id. Để biết các trường của tác vụ, xem Đối tượng tác vụ Keychain prototype.

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

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Bức ảnh cần chuyển thành ảnh khái niệm keychain, dưới dạng một URL công khai hoặc một data URI (data:image/jpeg;base64,<dữ liệu ảnh được mã hóa base64 của bạn>).
Ảnh phải là tệp JPG, JPEG, PNG, hoặc WebP có dung lượng tối đa 20 MB.
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ụ. Tên dài hơn sẽ trả về 400.
Nó dùng để gắn nhãn tác vụ trong bảng điều khiển và danh sách tác vụ của bạn, và không xuất hiện trên móc khóa. Để đặt tên trên móc khóa, hãy dùng name_text.
Name
name_text
Type
string
Description
Tên cần thêm vào móc khóa, chẳng hạn như tên của một thú cưng hoặc một người, tối đa 10 ký tự. Meshy đếm theo ký tự, 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 vừa. Tên dài hơn sẽ trả về 400. Bỏ trống trường này nếu muốn móc khóa không có tên.
Tên xuất hiện trên mặt móc khóa dưới dạng một chi tiết màu phẳng, không phải dạng chữ nổi hoặc chữ khắc.
Meshy cắt bỏ khoảng trắng xung quanh và loại bỏ các ký tự định dạng vô hình. Đối tượng tác vụ prototype trả về kết quả dưới dạng name_text, để bạn có thể kiểm tra văn bản trước khi trả tiền cho việc build.
Meshy thêm tên vào ở giai đoạn prototype. Bước build giữ nguyên tên đó, và bỏ qua name_text nếu được gửi đến endpoint build.
Khi văn bản không phải là ASCII thuần, hãy gửi nội dung yêu cầu dưới dạng UTF-8 với Content-Type: application/json; charset=utf-8. Một số HTTP client, chẳng hạn như Invoke-RestMethod của Windows PowerShell, mặc định mã hóa nội dung dưới dạng ISO-8859-1. Điều đó biến mọi ký tự không phải Latin thành ? trước khi yêu cầu đến được Meshy, và Meshy không thể phân biệt nó với một cái tên mà bạn thực sự muốn gửi.
Name
remove_background
Type
boolean
mặc định false
Description
Có xóa nền khỏi ảnh prototype hay không. true trả về một ảnh PNG RGBA trong suốt giữ nguyên toàn bộ huy hiệu (medallion), để bạn có thể đặt nó lên bất kỳ nền nào. Bước build cũng bắt đầu từ ảnh đã bỏ nền. Nếu Meshy không thể xóa nền, nó sẽ trả về ảnh kèm nền, và tác vụ vẫn thành công.
Tùy chọn remove_background của bước build là độc lập.

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 theo dõi luồng của nó cho đến khi status là SUCCEEDED. Sau đó truyền ID vào endpoint build dưới dạng input_task_id.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Ví dụ:
- image_url bị thiếu.
- Ảnh không phải là tệp JPG, JPEG, PNG, hoặc WebP.
- Ảnh quá nhỏ, vượt quá 20 MB, hoặc vượt quá số pixel tối đa.
- Meshy không thể tải ảnh xuống, ví dụ vì URL trả về 404 hoặc hết thời gian chờ.
- Data URI không phải là base64 hợp lệ.
- name_text dài hơn 10 ký tự. Meshy từ chối thay vì rút ngắn nó, và không tính phí cho yêu cầu đó.
- Ảnh hoặc name_text bị gắn cờ là nội dung không phù hợp (NSFW).
Thông báo lỗi sẽ cho biết vấn đề nào đã được phát hiện. Sửa yêu cầu, rồi 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 những 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.
- Tài khoản đang dùng gói miễn phí.
Kiểm tra tín dụng và gói của bạn, rồi thử lại.
Name
403 - Forbidden
Description
Nhóm của bạn đã bật IP Filtering, và Meshy đã gắn cờ ảnh vì vi phạm sở hữu trí tuệ của bên thứ ba. Hãy gửi một ảnh mà bạn có quyền sử dụng. Meshy chỉ kiểm tra sở hữu trí tuệ trên ảnh, không kiểm tra name_text.
Name
429 - Too Many Requests
Description
Một trong những giới hạn sau đã đạt đến:
- Bạn đã gửi nhiều yêu cầu hơn mức giới hạn tốc độ cho phép. Chờ vài giây, rồi thử lại. Xem Giới hạn tốc độ.
- Quá nhiều tác vụ của bạn đang xếp hàng hoặc đang chạy. Chờ một số tác vụ hoàn tất, rồi thử lại.
- Trên gói không giới hạn nhưng đã hết 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. Chờ một tác vụ hoàn tất, hoặc nạp thêm tín dụng.
Name
500 - Internal Server Error
Description
Meshy gặp lỗi máy chủ, ví dụ vì không thể chạy kiểm tra sở hữu trí tuệ trên ả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 đã tính phí. Hãy thử lại yêu cầu.

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

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

Tạo ra móc khóa có thể in 3D từ một tác vụ prototype đã thành công. Meshy biến ảnh ý tưởng (concept image) của prototype thành một bản nổi theo bản đồ độ sâu (depth-map relief), và trả về một tệp model theo định dạng bạn chọn. Để biết các trường của tác vụ, xem Đối tượng tác vụ build Keychain.

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

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/keychain/v1/prototype, với trạng thái SUCCEEDED.
Một ID không phải là tác vụ prototype Keychain nào của bạn từ API sẽ trả về 404, kể cả một prototype được tạo trong ứng dụng web.
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ụ. Tên dài hơn sẽ trả về 400.

`options`

Các cài đặt tùy chọn cho hình dạng của bản nổi. Mỗi trường đều có giá trị mặc định, vì vậy chỉ gửi những trường bạn muốn thay đổi. Giá trị nằm ngoài phạm vi của một trường sẽ trả về 400.

Name
badge_shape
Type
string
mặc định circle
Description
Đường viền của móc khóa khi Meshy không truy vết nó từ chủ thể. Meshy sử dụng giá trị này khi remove_background là false, hoặc khi nó không thể tìm thấy đường viền của chủ thể.
Các giá trị khả dụng:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
mặc định 40
Description
Độ dài cạnh của hình vuông bao quanh móc khóa, tính bằng milimét, tối đa 400. 0 sử dụng giá trị mặc định.
Name
relief_height_mm
Type
number
mặc định 2.2
Description
Chiều cao tối đa của bản nổi phía trên đế, tính bằng milimét, từ 0 đến 20.
Name
relief_offset_mm
Type
number
mặc định 0
Description
Hạ bản nổi xuống bao nhiêu, tính bằng milimét, từ 0 đến 20. Meshy trừ giá trị này khỏi chiều cao bản nổi ở mọi nơi, xuống đến tận đế.
Name
base_thickness_mm
Type
number
mặc định 0.1
Description
Độ dày của tấm đế phẳng phía sau bản nổi, tính bằng milimét, từ 0 đến 20.
Name
has_closed_back
Type
boolean
mặc định true
Description
Có đóng kín mặt sau của móc khóa hay không. false để mặt sau mở, dạng vỏ rỗng.
Name
relief_curve
Type
string
mặc định linear
Description
Đường cong ánh xạ giá trị bản đồ độ sâu thành chiều cao bản nổi.
Các giá trị khả dụng:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
mặc định 1.0
Description
Độ mạnh của đường cong, tối đa 10. Các đường cong gamma và s-curve sử dụng giá trị này, còn linear bỏ qua nó. 0 sử dụng giá trị mặc định.
Name
invert_depth
Type
boolean
mặc định false
Description
Có đảo ngược bản đồ độ sâu hay không, để vùng tối hơn trở thành bản nổi cao hơn.
Name
smoothing
Type
number
mặc định 0.24
Description
Mức độ làm mịn bản đồ độ sâu trước khi Meshy dựng bản nổi, từ 0 đến 10.
Name
relief_scale
Type
number
mặc định 1.0
Description
Mức độ phóng to bản nổi và texture của nó bên trong đường viền, quanh tâm, tối đa 10. Giá trị trên 1 sẽ phóng to chủ thể, và giá trị dưới 1 sẽ thu nhỏ nó. Nó không làm thay đổi chiều cao của bản nổi. 0 sử dụng giá trị mặc định.
Name
depth_threshold
Type
number
mặc định 0.1
Description
Giá trị bản đồ độ sâu mà dưới mức đó Meshy đặt độ sâu về 0, từ 0 đến 1.
Name
remove_background
Type
boolean
mặc định true
Description
Có truy vết đường viền của móc khóa từ chủ thể hay không, để móc khóa theo đúng hình dạng của chủ thể. false sẽ dùng đường viền badge_shape thay thế. Meshy cũng dùng badge_shape khi không thể tìm thấy đường viền của chủ thể.
Điều này tách biệt với tham số remove_background của prototype, vốn thiết lập xem ảnh prototype có nền trong suốt hay không.
Name
export_resolution
Type
integer
mặc định 512
Description
Độ phân giải lưới của model xuất ra, từ 64 đến 512. Meshy dựng hình học từ bản đồ độ sâu 512 pixel, vì vậy một lưới mịn hơn sẽ chỉ thêm mặt mà không thêm chi tiết. 0 sử dụng giá trị mặc định.

`output`

Tùy chọn. Thiết lập định dạng tệp mà build trả về.

Name
format
Type
string
mặc định glb
Description
Định dạng tệp mà build trả về.
Các giá trị khả dụng:
- glb: một tệp model.glb duy nhất, trong model_urls.glb
- obj: một tệp zip chứa model.obj, model.mtl, và texture.png, trong model_urls.obj
- zip: một tệp zip chứa mọi tệp mà Meshy tạo ra, trong model_urls.bundle_zip

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 truyền trực tuyến nó cho đến khi status là SUCCEEDED. Sau đó tải tệp xuống 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 thể chạy được. 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 chờ 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ó ảnh. Hãy tạo một tác vụ prototype mới.
- Một trường trong options nằm ngoài phạm vi hoặc không phải là một giá trị khả dụng.
Thông báo lỗi sẽ cho biết đã phát hiện vấn đề nào.
Name
401 - Unauthorized
Description
Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header 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.
- Tài khoản đang dùng 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ụ prototype Keychain nào do 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 chờ vài giây, rồi 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. Hãy chờ 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 chờ một tác vụ hoàn thành, hoặc nạp thêm tín dụng.

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

Lấy một tác vụ móc khóa

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 qua /prototype/:id sẽ trả về 404, và một tác vụ prototype được yêu cầu qua /build/:id cũng vậy.

Để biết các trường dữ liệu, xem Đối tượng tác vụ prototype móc khóa và Đối tượng tác vụ build móc khóa.

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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?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ùy theo giai đoạn khớp với đường dẫn.

Các chế độ thất bạ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 quyền 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ụ móc khóa 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à dùng /prototype hoặc /build sao cho khớp với tác vụ.
Name
500 - Internal Server Error
Description
Meshy không thể chạy kiểm tra quyền sở hữu trí tuệ. Hãy thử lại yêu cầu.

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

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

Hủy một tác vụ Keychain. 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ý tác vụ đó. 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/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).

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
Áp dụng một trong các trường hợp sau:
- 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ụ Keychain 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ụ.

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 của một tác vụ Keychain 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 duy nhất với status_code: 404 rồi đóng lại.

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 following PENDING frame is shortened 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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

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ụ Keychain trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường đầu ra của nó vẫ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 duy nhất thay cho kết quả đó, với status_code mà một yêu cầu get sẽ trả về.

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

Liệt kê các tác vụ Keychain

Trả về các tác vụ móc khóa 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/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=***"
    ]
  }
]

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. Giá trị 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ẽ 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 gồm 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 Keychain

Một tác vụ prototype tạo ra một hình ảnh ý tưởng được tô màu từ một bức ảnh. Để biến hình ảnh đó thành mô hình 3D, hãy truyền ID của tác vụ đến build endpoint dưới dạng input_task_id.

Thuộc tính

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

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-keychain-prototype.
Name
name
Type
string
Description
name bạn đã gửi khi tạo tác vụ, hoặc "" nếu bạn không gửi giá trị này.
Name
name_text
Type
string
Description
Tên mà Meshy đã thêm vào móc khóa, sau khi cắt bỏ khoảng trắng và loại bỏ các ký tự định dạng vô hình. Được bỏ qua khi bạn không gửi name_text. Để kiểm tra xem HTTP client của bạn đã mã hóa văn bản đúng cách hay chưa, hãy so sánh nó với những gì bạn đã 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, kèm 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ị này là 0 cho đến khi tác vụ bắt đầu và là 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 thực hiện tác vụ, tính bằng mili giây Unix. Là null cho đến lúc đó.
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. 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. Giá trị 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 Enterprise, vốn giữ kết quả API vô thời hạn, giá trị 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à tác vụ sẽ bắt đầu tiếp theo. 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. Là null trừ khi status là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng bị tính phí cho tác vụ, sau khi đã hoàn trả (nếu có). Một request trả về lỗi sẽ không bị tính phí. Một tác vụ thất bại sẽ có giá trị 0, vì Meshy sẽ hoàn trả lại. Việc hủy chỉ hoàn trả 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 request danh sách sẽ trả về 500. Trong trường hợp đó, hãy thử lại request.
Name
image_urls
Type
array of strings
Description
URL tải xuống cho hình ảnh ý tưởng. Mảng này có một URL sau khi tác vụ thành công, và trống cho đến lúc đó.

Đối tượng tác vụ dựng móc khóa

Một tác vụ dựng tạo ra móc khóa 3D từ một tác vụ prototype đã thành công. Nó trả về một tệp mô hình theo định dạng bạn đã yêu cầu.

Thuộc tính

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

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-keychain-build.
Name
name
Type
string
Description
name 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ó kết quả
- FAILED: trạng thái cuối, với 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 nó 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 lúc đó.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ đạt trạng thái cuối cùng, tính bằng mili giây Unix. 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. Giá trị 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 các tài khoản Doanh nghiệp, vốn giữ lại kết quả API vô thời hạn, giá trị 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. 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ị trừ cho tác vụ, sau khi hoàn lại (nếu có). Một yêu cầu trả về lỗi sẽ không bị trừ tín dụng. 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 lại tín dụng của 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 tệp mô hình, với một mục cho output.format bạn đã yêu cầu. {} cho đến khi tác vụ thành công.
- Name
  glb
  Type
  string
  Description
  URL tải xuống cho tệp GLB. Xuất hiện khi output.format là glb.
- Name
  obj
  Type
  string
  Description
  URL tải xuống cho một tệp 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 tải xuống cho một tệp zip chứa mọi tệp mà Meshy tạo ra. Xuất hiện khi output.format là zip.