API Đổi kích thước

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, một ràng buộc 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ụ Đổi kích thước

endpoint này tạo một tác vụ đổi kích thước mới.

Tham số

Chỉ bắt buộc một trong input_task_id hoặc model_url. Nếu cả hai được cung cấp, input_task_id có độ ưu tiên cao hơn.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ Meshy đã hoàn tất có model 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 model 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. Định dạng đầu ra sẽ giữ nguyên định dạng gốc của model đầu vào.

Bắt buộc chính xác một mode đổi kích thước: 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 model thành một chiều cao cụ thể được đo bằng mét.

Name
resize_longest_side
Type
number
Description
Đổi kích thước model 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 thị giác AI để tự động ước tính chiều cao thực tế của đối tượng và đổi kích thước model tương ứng. Gốc tọa độ (origin) 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.

Trả về

Thuộc tính result của phản hồi chứa id của tác vụ đổi kích thước mới được tạo.

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

400 - Bad Request

Yêu cầu không được chấp nhận. Các nguyên nhân thường gặp:

Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
Thiếu mode đổi kích thước: Phải chỉ định ít nhất một trong resize_height, resize_longest_side, hoặc auto_size.
Các tham số loại trừ lẫn nhau: Không thể kết hợp resize_height, resize_longest_side, và auto_size.
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 model 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.

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

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

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

Trả về

Trả về 200 OK khi thành công.

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

// Returns 200 Ok on success.

GET/openapi/v1/resize

Liệt kê tác vụ Đổi kích thước

endpoint này cho phép bạn truy xuất danh sách các tác vụ đổi kích thước.

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 kích thước trang. Tối đa được phép là 50 mục.

Name
sort_by
Type
string
Description
Trường để sắp xếp theo. Các giá trị khả dụng:
- +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 được phân trang của Các Đối tượng tác vụ Đổi kích thước.

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 phát một tác vụ Đổi kích thước

endpoint này truyền phát 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 phát.

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
}

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

Đối tượng tác vụ Đổi kích thước đại diện cho một công việc đổi kích thước.

Thuộc tính

id · string

Mã định danh duy nhất cho tác vụ.

type · string

Loại tác vụ. Giá trị là resize.

model_urls · object

URL có thể tải xuống cho tệp mô hình đã đổi kích thước. Khi sử dụng input_task_id, đầu ra luôn là GLB. Khi sử dụng model_url, đầu ra giữ nguyên định dạng gốc.

progress · integer

progress của tác vụ (0-100).

status · string

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

preceding_tasks · integer

Số lượng tác vụ đứng trước. Chỉ có ý nghĩa khi trạng thái là PENDING.

created_at · timestamp

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

started_at · timestamp

Dấu thời gian khi tác vụ đượ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 tác vụ được hoàn tất, tính bằng mili giây. 0 nếu chưa hoàn tất.

task_error · object

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

consumed_credits · integer

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