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ó thành 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 một Nhiệm vụ Đổi kích thước

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

Tham số

Chỉ một trong input_task_id hoặc model_url là bắt buộc. Nếu cả hai đượ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 nhiệm vụ Meshy đã hoàn thành mà bạn muốn đổi kích thước. Nhiệm vụ phải có trạng thái là SUCCEEDED. Định dạng đầu ra sẽ là GLB.

Name
model_url
Type
string
Bắt buộc
Description
Một URL công khai hoặc Data URI trỏ đến một tệp mô hình 3D. Các định dạng được hỗ trợ: .glb, .gltf, .obj, .fbx, .stl. Đối với Data URIs, sử dụng MIME type: application/octet-stream. Định dạng đầu ra sẽ giữ nguyên định dạng gốc của mô hình đầu vào.

Chính xác một chế độ đổi kích thước là bắt buộ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 mô hình đến một chiều cao cụ thể đ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, đ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 tương ứng. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được thiết lập 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ị có sẵn: bottom, center.

Trả về

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

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

400 - Bad Request

Yêu cầu không chấp nhận đượ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 chế độ đổi kích thước: Ít nhất một trong resize_height, resize_longest_side, hoặc auto_size phải được chỉ định.
Tham số loại trừ lẫn nhau: resize_height, resize_longest_side, và auto_size không thể kết hợp.
Nhiệm vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một nhiệm 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: model_url không thể tải xuống.

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 nhiệm 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 bằng 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.

Yêu cầu

GET

/openapi/v1/resize/:id

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

Phản hồi

{
  "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 Nhiệm vụ Đổi kích thước

Endpoint này xóa vĩnh viễn một nhiệm 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ể đảo ngược.

Tham số Đường dẫn

Name
id
Type
path
Description
ID của nhiệm vụ đổi kích thước cần xóa.

Trả về

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

Yêu cầu

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

Phản hồi

// Returns 200 Ok on success.

GET/openapi/v1/resize

Danh sách Nhiệm vụ Đổi kích thước

Endpoint này cho phép bạn truy xuất danh sách các nhiệm 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 cho phép là 50 mục.

Name
sort_by
Type
string
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 tăng dần.
- -created_at: Sắp xếp theo thời gian tạo giảm dần.

Trả về

Trả về danh sách phân trang của Các Đối tượng Nhiệm vụ Đổi kích thước.

Yêu cầu

GET

/openapi/v1/resize

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

Phản hồi

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

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

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ đổi kích thước để phát trực tuyến.

Trả về

Trả về một luồng của Các Đố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.

Yêu cầu

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

Luồng Phản hồi

// 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 Nhiệm vụ Đổi kích thước

Đối tượng Nhiệm 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

Định danh duy nhất cho nhiệm vụ.

type · string

Loại của nhiệm vụ. Giá trị là resize.

model_urls · object

URL có thể tải xuống cho tệp mô hình đã được đổ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 ban đầu.

progress · integer

Tiến độ của nhiệm vụ (0-100).

status · string

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

preceding_tasks · integer

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

created_at · dấu thời gian

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

started_at · dấu thời gian

Dấu thời gian khi nhiệm vụ bắt đầu, tính bằng mili giây. 0 nếu chưa bắt đầu.

finished_at · dấu thời gian

Dấu thời gian khi nhiệm vụ 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 nhiệm 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 đã tiêu thụ bởi nhiệm vụ này (1 tín dụng cho mỗi nhiệm vụ đổi kích thước). Trả về 0 cho các nhiệm vụ FAILED.