Resize API

API Đổi kích thước cho phép bạn đổi kích thước các mô hình 3D hiện có theo kích thước thực tế. Bạn có thể chỉ định chiều cao chính xác, giới hạn theo cạnh dài nhất, hoặc để AI tự động ước tính kích thước phù hợp.

POST/openapi/v1/resize

Tạo tác vụ Resize

endpoint này tạo một tác vụ resize mới.

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

Tham số

Chỉ một trong hai tham số input_task_id hoặc model_url là bắt buộc. Nếu cả hai đều được cung cấp, input_task_id sẽ được ưu tiên.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ Meshy đã hoàn thành có mô hình mà bạn muốn đổi kích thước. Tác vụ phải có trạng thái SUCCEEDED. Định dạng đầu ra sẽ là GLB.

Name
model_url
Type
string
Bắt buộc
Description
Một URL có thể truy cập công khai hoặc data URI trỏ đến tệp mô hình 3D. Các định dạng được hỗ trợ: .glb, .gltf, .obj, .fbx, .stl. Đối với Data URI, hãy sử dụng MIME type: application/octet-stream. URL .glb, .obj, .fbx hoặc .stl sẽ giữ nguyên định dạng của nó trong đầu ra; URL .gltf hoặc data URI sẽ tạo ra GLB.
Kích thước tệp tối đa: 400 MB đối với URL http hoặc https, 100 MB đối với URI data:.
Tệp GLB, glTF, FBX hoặc OBJ vượt quá 100 MB có thể có tối đa 10.000.000 mặt. Mặt được tính là tam giác: một hình tứ giác được tính là 2, và một lưới được vẽ nhiều lần được tính một lần cho mỗi bản sao. Đối với tệp vượt quá 100 MB, tệp FBX phải là FBX nhị phân 7.1 trở lên, và tệp GLB hoặc glTF không được sử dụng nén Draco.

Cần chọn chính xác một mode resize: resize_height, resize_longest_side, hoặc auto_size. Ba tham số này loại trừ lẫn nhau.

Name
resize_height
Type
number
Description
Đổi kích thước mô hình theo chiều cao cụ thể được đo bằng mét.

Name
resize_longest_side
Type
number
Description
Đổi kích thước mô hình sao cho cạnh dài nhất của nó khớp với giá trị này, được đo bằng mét. Tỷ lệ khung hình được giữ nguyên.

Name
auto_size
Type
boolean
Description
Khi được đặt thành true, dịch vụ sử dụng AI vision để tự động ước tính chiều cao thực tế của đối tượng và đổi kích thước mô hình cho phù hợp. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được đặt rõ ràng.

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí của gốc tọa độ sau khi đổi kích thước.
Các giá trị khả dụng: bottom, center.

Giá trị trả về

Thuộc tính result của phản hồi chứa id của tác vụ resize vừa được tạo.

Các chế độ lỗi

400 - Bad Request

Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:

Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
Thiếu mode resize: Phải chỉ định ít nhất một trong các tham số resize_height, resize_longest_side, hoặc auto_size.
Các tham số loại trừ lẫn nhau: resize_height, resize_longest_side, và auto_size không thể kết hợp với nhau.
Tác vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một tác vụ thành công.
Định dạng mô hình không hợp lệ: model_url trỏ đến một tệp có phần mở rộng không được hỗ trợ.
URL không thể truy cập: Không thể tải xuống model_url.
Tệp mô hình quá lớn: Tệp model_url vượt quá 400 MB (URL http hoặc https) hoặc 100 MB (URI data:).
Quá nhiều mặt: Tệp model_url vượt quá 100 MB và có hơn 10.000.000 mặt. Hãy giảm số lượng mặt, sau đó gửi lại tệp.
FBX ASCII vượt quá 100 MB: Tệp model_url là FBX ASCII 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 thể đọc được: Tệp model_url vượt quá 100 MB và không thể đọc được header của nó, ví dụ như GLB hoặc glTF được nén Draco, hoặc 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à header của nó có quá nhiều lưới, node hoặc bản ghi để kiểm tra. Hãy giảm số lượng đối tượng trong tệp, sau đó gửi lại.

401 - Unauthorized

Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.

402 - Payment Required

Không đủ tín dụng để thực hiện tác vụ này.

429 - Too Many Requests

Bạn đã vượt quá giới hạn tốc độ của mình.

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

GET/openapi/v1/resize/:id

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

Endpoint này truy xuất một tác vụ đổi kích thước theo ID của nó.

Tham số

Name
id
Type
path
Description
ID của tác vụ đổi kích thước cần truy xuất.

Giá trị trả về

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

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
}

DELETE/openapi/v1/resize/:id

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

Endpoint này xóa vĩnh viễn một tác vụ Đổi kích thước, bao gồm tất cả các mô hình và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số đường dẫn (Path Parameters)

Name
id
Type
path
Description
ID của tác vụ Đổi kích thước cần xóa.

Trạng thái tác vụ

Một tác vụ vẫn còn ở trạng thái PENDING sẽ được xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đã ở trạng thái IN_PROGRESS thì không thể xóa: yêu cầu sẽ bị từ chối với mã 409 Conflict và tác vụ vẫn tiếp tục chạy. Tín dụng cho một tác vụ mà worker đã bắt đầu xử lý thì không thể hoàn lại, vì vậy việc xóa nó giữa chừng 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.

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

Kết quả trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/resize

List Resize Tasks

Endpoint này cho phép bạn truy xuất danh sách các tác vụ resize.

Tham số

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 số lượng mục trên mỗi trang. Tối đa cho phép là 100 mục.

Name
sort_by
Type
string
Description
Trường dùng để sắp xếp. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo tăng dần.
- -created_at: Sắp xếp theo thời gian tạo giảm dần.

Kết quả trả về

Trả về danh sách phân trang của Đối tượng Tác vụ Resize.

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

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

Truyền trực tuyến một tác vụ Đổi kích thước

Endpoint này truyền trực tuyến các cập nhật theo thời gian thực cho một tác vụ đổi kích thước bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ đổi kích thước cần truyền trực tuyến.

Giá trị trả về

Trả về một luồng Đối tượng Tác vụ Đổi kích thước dưới dạng Server-Sent Events.

Đối với các tác 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/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
}

The Resize Task Object

Resize Task object đại diện cho một công việc đổi kích thước.

Properties

id · string

Mã định danh duy nhất cho task.

type · string

Loại của task. Giá trị là resize.

model_urls · object

URL có thể tải xuống cho tệp model đã đổi kích thước. Khi sử dụng input_task_id, đầu ra luôn là GLB. Khi sử dụng model_url, một đầu vào .glb, .obj, .fbx hoặc .stl sẽ giữ nguyên định dạng của nó, còn đầu vào .gltf hoặc một Data URI sẽ tạo ra GLB.

progress · integer

Progress của task (0-100).

status · string

Trạng thái của task. Các giá trị có thể có: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Số lượng các task đứng trước. Chỉ có ý nghĩa khi status là PENDING.

created_at · timestamp

Dấu thời gian khi task được tạo, tính bằng mili giây.

started_at · timestamp

Dấu thời gian khi task được bắt đầu, tính bằng mili giây. 0 nếu chưa bắt đầu.

finished_at · timestamp

Dấu thời gian khi task hoàn thành, tính bằng mili giây. 0 nếu chưa hoàn thành.

task_error · object

Đối tượng lỗi nếu task thất bại. Xem Lỗi để biết thêm chi tiết.

consumed_credits · integer

Số lượng tín dụng đã tiêu thụ bởi task này (1 tín dụng cho mỗi task đổi kích thước). Trả về 0 đối với các task FAILED.