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

POST/openapi/v1/convert

Tạo một Nhiệm vụ Chuyển đổi

Endpoint này tạo một nhiệm 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 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 chuyển đổi mô hình. Nhiệm vụ phải có trạng thái là SUCCEEDED.

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.

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. Các giá trị có sẵn: 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 nhiệm vụ chuyển đổi 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. 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 target_formats: Phải chỉ định ít nhất một định dạng đích.
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/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 Nhiệm vụ Chuyển đổi

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

Tham số

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

Trả về

Đối tượng Nhiệm vụ Chuyển đổi.

Yêu cầu

GET

/openapi/v1/convert/:id

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

Phản hồi

{
  "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 Nhiệm vụ Chuyển đổi

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

Tham số Đường dẫn

Name
id
Type
path
Description
ID của nhiệm vụ chuyển đổi cần xóa.

Trả về

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

Yêu cầu

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

Phản hồi

// Returns 200 Ok on success.

GET/openapi/v1/convert

Danh sách các 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 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 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 phân trang của Các Đối tượng Tác vụ Chuyển đổi.

Yêu cầu

GET

/openapi/v1/convert

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

Phản hồi

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

Phát trực tuyến một Nhiệm vụ Chuyển đổi

Endpoint này phát trực tuyến các cập nhật thời gian thực cho một nhiệm vụ chuyển đổi bằng cách sử dụng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho nhiệm vụ chuyển đổi để phát trực tuyến.

Trả về

Trả về một luồng của Các Đối tượng Nhiệm vụ Chuyển đổi dưới dạng Server-Sent Events.

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

curl -N https://api.meshy.ai/openapi/v1/convert/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": "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 Nhiệm vụ Chuyển đổi

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

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

type · chuỗi

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

model_urls · đối tượng

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 trống.

progress · số nguyên

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

status · chuỗi

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

preceding_tasks · số nguyên

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 · đối tượng

Đố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 · số nguyên

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ụ chuyển đổi). Trả về 0 cho các nhiệm vụ FAILED.