Resize API

API Resize cho phép bạn đổi kích thước các mô hình 3D hiện có về kích thước thực tế. Bạn có thể chỉ định chiều cao chính xác, 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

Create a Resize Task

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

Tham số

Chỉ một trong hai 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 mà bạn muốn đổi kích thước mô hình của nó. Tác 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ó thể truy cập 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 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 mô hình đầu vào.

Bắt buộc phải có 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 về 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 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 sẽ được giữ nguyên.

  • Name
    auto_size
    Type
    boolean
    Description

    Khi được đặt thành true, dịch vụ sẽ 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 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ị khả dụng: bottom, center.

Kết quả 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 trỏ đế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.
  • 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 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ạng thái tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ được xóa và số tín dụng đã tiêu tốn lúc 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ý sẽ không được 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

Danh sách các 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 cho phép là 100 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.

Giá trị trả về

Trả về một danh sách phân trang gồm 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

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

Endpoint này stream 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

    Định danh duy nhất của tác vụ đổi kích thước cần stream.

Giá trị trả về

Trả về một luồng gồm 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ụ ở trạng thái 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

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

Properties

  • id · string

Đị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 đã đượ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 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ụ đang đứ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ụ 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 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 đã tiêu thụ bởi tác vụ này (1 tín dụng cho mỗi tác vụ resize). Trả về 0 đối với các tác vụ FAILED.