Convert API

Convert API cho phép bạn chuyển đổi các mô hình 3D hiện có sang các định dạng file khác.

POST/openapi/v1/convert

Xóa một tác vụ Chuyển đổi

Endpoint này xóa vĩnh viễn một tác vụ chuyển đổi, 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ụ chuyển đổi 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ý 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 chờ cho đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, rồi mới xóa nó.

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 hoàn lại 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/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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/convert

Liệt kê Convert Tasks

Endpoint này cho phép bạn lấy danh sách các convert task.

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

Trả về

Trả về một danh sách phân trang gồm Các đối tượng Convert Task.

Request

GET

/openapi/v1/convert

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

Response

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

GET/openapi/v1/convert/:id/stream

Stream một Convert Task

Endpoint này truyền (stream) các cập nhật theo thời gian thực cho một convert task bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của convert task cần stream.

Kết quả trả về

Trả về một luồng (stream) các The Convert Task Objects dưới dạng Server-Sent Events.

Đối với các task ở 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/convert/:id/stream

curl -N https://api.meshy.ai/openapi/v1/convert/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": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Đối tượng Convert Task

Đối tượng Convert Task đại diện cho một tác vụ chuyển đổi định dạng.

Properties

id · string

Định danh duy nhất cho tác vụ.

type · string

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

model_urls · object

Các URL có thể tải xuống cho các tệp mô hình đã chuyển đổi. Chỉ các định dạng được chỉ định trong target_formats mới có URL. Các thuộc tính định dạng khác sẽ là chuỗi rỗng.

progress · integer

Tiến trình của tác vụ (0-100).

status · string

Trạng thái của tác vụ. Các giá trị có thể có: 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ụ 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ụ convert). Trả về 0 đối với các tác vụ FAILED.

Convert API

Create a Convert Task

Tham số

Giá trị trả về

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

Request

Response

Truy xuất tác vụ Chuyển đổi

Tham số

Kết quả trả về

Request

Response

Xóa một tác vụ Chuyển đổi

Tham số đường dẫn

Trạng thái tác vụ

Kết quả trả về

Request

Response

Liệt kê Convert Tasks

Tham số

Trả về

Request

Response

Stream một Convert Task

Tham số

Kết quả trả về

Request

Response Stream

Đối tượng Convert Task

Properties