API Chuyển đổi

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

POST/openapi/v1/convert

Tạo tác vụ Chuyển đổi

endpoint này tạo một tác vụ chuyển đổi định dạng mới.

Tham số

Chỉ một trong input_task_id hoặc model_url là bắt buộc. Nếu cung cấp cả hai, 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 tất có mô hình mà bạn muốn chuyển đổi. Tác vụ phải có trạng thái SUCCEEDED.

Name
model_url
Type
string
Bắt buộc
Description
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.

Name
target_formats
Type
string[]
Bắt buộc
Description
Danh sách các định dạng đầu ra cho mô hình đã chuyển đổi. Giá trị khả dụng: glb, fbx, obj, usdz, blend, stl, 3mf.

Trả về

Thuộc tính result của phản hồi chứa id của tác vụ convert 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 target_formats: Phải chỉ định ít nhất một định dạng đích.
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.

401 - Unauthorized

Xác thực không thành công. 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/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/convert/:id

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

endpoint này truy xuất một tác vụ chuyển đổi theo ID của tác vụ đó.

Tham số

Name
id
Type
path
Description
ID của tác vụ chuyển đổi cần truy xuất.

Trả về

Đối tượng Tác vụ Chuyển đổi.

Request

GET

/openapi/v1/convert/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "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
}

DELETE/openapi/v1/convert/:id

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ả về

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

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Liệt kê tác vụ Chuyển đổi

endpoint này cho phép bạn truy xuất danh sách các tác vụ Chuyển đổi.

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ị có sẵn:
- +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 Đối tượng tác vụ Chuyển đổi.

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

Truyền phát một tác vụ Chuyển đổi

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ụ chuyển đổi bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ chuyển đổi cần truyền phát.

Trả về

Trả về một luồng Các đối tượng tác vụ Chuyển đổi 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/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 Tác vụ Chuyển đổi

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

Thuộc tính

id · string

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

type · string

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

model_urls · object

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 độ 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 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 tác vụ này tiêu thụ (1 tín dụng cho mỗi tác vụ chuyển đổi). Trả về 0 cho các tác vụ FAILED.