Resize API

Đổi kích thước một mô hình 3D theo kích thước thực tế, tính bằng mét. Đặt chiều cao của nó hoặc chiều dài của cạnh dài nhất, hoặc để Meshy ước tính chiều cao thực tế của đối tượng.

POST/openapi/v1/resize

Tạo một tác vụ Resize

Tạo một tác vụ Resize. Tác vụ này chạy ngầm. Để biết thời gian một tác vụ thường mất bao lâu, xem Thời gian xử lý.

Request

POST

/openapi/v1/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi model_url. ID của một tác vụ đã tạo ra mô hình 3D, ví dụ một tác vụ Text to 3D, Image to 3D, Remesh, hoặc Retexture. Tác vụ phải đến từ API và có trạng thái SUCCEEDED. Meshy trả về mô hình đã đổi kích thước dưới dạng tệp GLB.

Name
model_url
Type
string
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi input_task_id. Mô hình cần đổi kích thước, dưới dạng URL công khai hoặc data URI. Nếu bạn gửi cả hai, Meshy sẽ dùng input_task_id.
Mô hình phải là tệp GLB, glTF, OBJ, FBX, hoặc STL có dung lượng tối đa 400 MB từ URL http hoặc https, hoặc 100 MB nếu là data URI. Đối với data URI, dùng MIME type application/octet-stream.
Một tệp trên 100 MB cũng phải tuân theo các quy tắc sau:
- Một tệp GLB, glTF, FBX, hoặc OBJ có thể có tối đa 10.000.000 mặt. Meshy tính mặt theo tam giác, vì vậy một mặt tứ giác được tính là 2, và một lưới được vẽ nhiều lần sẽ được tính một lần cho mỗi bản sao.
- Một tệp FBX phải là FBX nhị phân phiên bản 7.1 trở lên.
- Một tệp GLB hoặc glTF không được dùng nén Draco.
Tệp GLB, OBJ, FBX, hoặc STL sẽ giữ nguyên định dạng trong kết quả. Một tệp .gltf hoặc data URI sẽ được trả về dưới dạng GLB.

Gửi chính xác một trong các tham số resize_height, resize_longest_side, hoặc auto_size. Nếu không gửi tham số nào trong số đó, hoặc gửi nhiều hơn một, sẽ trả về 400.

Name
resize_height
Type
number
Description
Chiều cao mới của mô hình tính bằng mét, lớn hơn 0. Giá trị âm sẽ trả về 400.

Name
resize_longest_side
Type
number
Description
Độ dài mới của cạnh dài nhất của mô hình tính bằng mét, lớn hơn 0. Giá trị âm sẽ trả về 400. Meshy giữ nguyên tỉ lệ khung hình của mô hình.

Name
auto_size
Type
boolean
Description
Có ước tính chiều cao thực tế của vật thể bằng AI thị giác và đổi kích thước mô hình theo chiều cao đó hay không. Trừ khi bạn thiết lập origin_at, Meshy sẽ đặt gốc tọa độ ở đáy.

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí đặt gốc tọa độ của mô hình sau khi đổi kích thước, bottom hoặc center.

Giá trị trả về

Trường result của phản hồi chứa ID của tác vụ Resize mới.

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

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Thông báo lỗi cho biết vấn đề nào đã được phát hiện. Ví dụ:
- Thiếu tham số: Không gửi cả model_url lẫn input_task_id.
- Thiếu mode resize: Không gửi tham số nào trong số resize_height, resize_longest_side, và auto_size.
- Các tham số loại trừ lẫn nhau: Yêu cầu có nhiều hơn một trong số resize_height, resize_longest_side, và auto_size. Chỉ gửi một.
- Kích thước âm: resize_height hoặc resize_longest_side có giá trị âm.
- Tác vụ đầu vào không hợp lệ: input_task_id không phải là một tác vụ API thành công có tệp mô hình.
- Định dạng mô hình không hợp lệ: Tệp model_url có phần mở rộng không được hỗ trợ.
- URL không thể truy cập: Meshy không thể tải xuống tệp model_url.
- Tệp mô hình quá lớn: Tệp model_url vượt quá 400 MB từ URL http hoặc https, hoặc vượt quá 100 MB nếu là data URI.
- Quá nhiều mặt: Tệp model_url vượt quá 100 MB và có nhiều hơn 10.000.000 mặt. Giảm số lượng mặt, sau đó gửi lại tệp.
- ASCII FBX trên 100 MB: Tệp model_url là ASCII FBX vượt quá 100 MB. Hãy gửi dưới dạng FBX nhị phân hoặc GLB.
- Tệp mô hình không đọc được: Tệp model_url vượt quá 100 MB, và Meshy không thể đọc phần header của tệp. Ví dụ, đó là một tệp GLB hoặc glTF được nén Draco, hoặc một FBX nhị phân cũ hơn phiên bản 7.1.
- Header mô hình quá phức tạp: Tệp model_url vượt quá 100 MB, và phần header có quá nhiều lưới, node, hoặc bản ghi để kiểm tra. Giảm số lượng đối tượng trong tệp, sau đó gửi lại.
Sửa yêu cầu, sau đó gửi lại. Xem Lỗi.
Name
401 - Unauthorized
Description
Thiếu khóa API hoặc khóa API không hợp lệ. Kiểm tra header Authorization.
Name
402 - Payment Required
Description
Ví dụ:
- Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt giới hạn tín dụng. Kiểm tra số dư tín dụng của bạn, sau đó thử lại.
- Gói miễn phí: Việc tạo tác vụ yêu cầu gói trả phí. Nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.
Name
403 - Forbidden
Description
input_task_id là một mô hình phù điêu, mà endpoint này không thể đổi kích thước. Thông báo là This model type does not support this operation. Hãy gửi một mô hình khác.
Name
404 - Not Found
Description
input_task_id không khớp với bất kỳ tác vụ nào của bạn. Kiểm tra ID tác vụ, sau đó gửi lại yêu cầu.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Hãy đợi, sau đó thử lại. Xem Giới hạn tốc độ.

GET/openapi/v1/resize/:id

Lấy một tác vụ Đổi kích thước

Trả về một tác vụ Đổi kích thước theo ID của nó.

Request

GET

/openapi/v1/resize/:id

curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Tham số

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

Giá trị trả về

Đối tượng tác vụ Đổi kích thước.

DELETE/openapi/v1/resize/:id

Xóa một tác vụ Đổi kích thước

Xóa vĩnh viễn một tác vụ Đổi kích thước, bao gồm các mô hình và dữ liệu của nó. Bạn không thể hoàn tác việc xóa.

Request

DELETE

/openapi/v1/resize/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ cần xóa.

Trạng thái tác vụ

Xóa một tác vụ PENDING sẽ hoàn lại số tín dụng đã sử dụng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn tín dụng cho một tác vụ đã bắt đầu chạy, vì vậy việc xóa nó sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, sau đó mới xóa nó.

Việc xóa một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) sẽ không hoàn lại tín dụng.

Giá trị trả về

200 OK khi tác vụ được xóa, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

GET/openapi/v1/resize

Danh sách tác vụ Đổi kích thước

Trả về danh sách các tác vụ Đổi kích thước của bạn.

Request

GET

/openapi/v1/resize

curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Số trang cần trả về, tối đa 255. Giá trị lớn hơn 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.

Name
sort_by
Type
string
Description
Thứ tự sắp xếp.
Các giá trị khả dụng:
- +created_at: cũ nhất trước
- -created_at: mới nhất trước

Giá trị trả về

Một danh sách có phân trang gồm đối tượng tác vụ Đổi kích thước.

GET/openapi/v1/resize/:id/stream

Stream một tác vụ Resize

Truyền các cập nhật của tác vụ Resize dưới dạng Server-Sent Events (SSE).

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Tham số

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

Giá trị trả về

Một luồng các đối tượng tác vụ Resize dưới dạng Server-Sent Events.

Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, theo cùng định dạng mà endpoint Get trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường kết quả của nó chưa có giá trị.

Đối tượng tác vụ Resize

Đối tượng tác vụ Resize mô tả một lần đổi kích thước mô hình 3D. Nó lưu trạng thái, progress và tệp mô hình khi tác vụ thành công.

Thuộc tính

Name
id
Type
string
Description
ID của tác vụ. Hãy xem đây là một chuỗi không minh bạch (opaque string), 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à resize.
Name
model_urls
Type
object
Description
URL tải xuống cho tệp mô hình đã đổi kích thước. Đối với input_task_id, tệp luôn là GLB. Đối với model_url, tệp GLB, OBJ, FBX hoặc STL sẽ giữ nguyên định dạng, còn tệp .gltf hoặc Data URI sẽ được trả về dưới dạng GLB.
Name
progress
Type
integer
Description
Mức độ hoàn thành của tác vụ, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.
Name
status
Type
string
Description
Trạng thái của tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED hoặc CANCELED.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi tác vụ đang ở trạng thái PENDING.
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 tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ bắt đầu.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.
Name
expires_at
Type
timestamp
Description
Thời điểm các URL tải xuống của tác vụ hết hạn, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.
Name
texture_urls
Type
array
Description
URL tải xuống cho các texture map của mô hình, khi tác vụ thành công: một mảng các đối tượng, mỗi đối tượng ứng với một bộ texture. Mỗi đối tượng có một URL base_color, và cũng có thể có các URL metallic, roughness, normal, emission và metallic_roughness. Giá trị là null cho đến khi tác vụ thành công, và là một mảng rỗng khi mô hình không có texture map nào.
Name
task_error
Type
object
Description
Chi tiết lỗi khi tác vụ thất bại. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số tín dụng mà tác vụ đã sử dụng, là 1 đối với một tác vụ Resize. Giá trị là 0 đối với tác vụ FAILED.