lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

Convert API

Chuyển đổi một mô hình 3D sang các định dạng tệp khác, từ một tác vụ Meshy hoặc từ một tệp mô hình.

POST/openapi/v1/convert

Tạo tác vụ Convert

Tạo một tác vụ Convert. Tác vụ chạy ở chế độ nền. Để biết thời gian một tác vụ thường mất bao lâu, xem Thời gian xử lý.

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

Tham số

  • Name
    input_task_id
    Type
    string
    Bắt buộc
    Description

    Bắt buộc trừ khi bạn gửi model_url. ID của một tác vụ đã tạo ra mô hình 3D, ví dụ như tác vụ Văn bản sang 3D, Ảnh sang 3D, Remesh, Đổi kích thước, hoặc Tạo lại texture. Tác vụ đó phải đến từ API và có trạng thái SUCCEEDED.

  • Name
    model_url
    Type
    string
    Bắt buộc
    Description

    Bắt buộc trừ khi bạn gửi input_task_id. Mô hình cần chuyển đổi, dưới dạng URL công khai hoặc Data URI. Nếu bạn gửi cả hai, Meshy sẽ dùng input_task_id.

    Mô hình phải là tệp GLB, glTF, OBJ, FBX, hoặc STL có dung lượng tối đa 400 MB từ URL http hoặc https, hoặc 100 MB nếu là Data URI. Đối với Data URI, hãy dùng MIME type application/octet-stream.

    Một tệp vượt quá 100 MB cũng phải tuân theo các quy tắc sau:

    • Tệp GLB, glTF, FBX, hoặc OBJ có thể có tối đa 10.000.000 mặt. Meshy đếm mặt theo tam giác, vì vậy một tứ giác được tính là 2, và một lưới được vẽ nhiều lần được tính một lần cho mỗi bản sao.
    • Tệp FBX phải là FBX nhị phân phiên bản 7.1 trở lên.
    • Tệp GLB hoặc glTF không được dùng nén Draco.
  • Name
    target_formats
    Type
    string[]
    Bắt buộc
    Description

    Các định dạng tệp cần tạo. Liệt kê ít nhất một định dạng. Danh sách thiếu hoặc rỗng sẽ trả về 400.

    Các giá trị khả dụng:

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

Giá trị trả về

Trường result của phản hồi chứa ID của tác vụ Convert mới.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể chạy được. Thông báo lỗi cho biết vấn đề đã phát hiện. Ví dụ:

    • Thiếu tham số: Không có model_url hoặc input_task_id nào được gửi.
    • Thiếu target_formats: target_formats bị thiếu hoặc không liệt kê định dạng nào.
    • Tác vụ đầu vào không hợp lệ: input_task_id không phải là một tác vụ API thành công có kèm tệp mô hình.
    • Định dạng mô hình không hợp lệ: Tệp model_url có phần mở rộng không được hỗ trợ.
    • URL không thể truy cập: Meshy không thể tải xuống tệp model_url.
    • Tệp mô hình quá lớn: Tệp model_url vượt quá 400 MB từ URL http hoặc https, hoặc vượt quá 100 MB nếu là Data URI.
    • Quá nhiều mặt: Tệp model_url vượt quá 100 MB và có hơn 10.000.000 mặt. Hãy giảm số lượng mặt, sau đó gửi lại tệp.
    • FBX ASCII vượt quá 100 MB: Tệp model_url là FBX dạng ASCII vượt quá 100 MB. Hãy gửi dưới dạng FBX nhị phân hoặc GLB.
    • Tệp mô hình không đọc được: Tệp model_url vượt quá 100 MB, và Meshy không thể đọc phần header của nó. Ví dụ, đó là một tệp GLB hoặc glTF được nén Draco, hoặc một tệp FBX nhị phân cũ hơn phiên bản 7.1.
    • Header mô hình quá phức tạp: Tệp model_url vượt quá 100 MB, và phần header của nó có quá nhiều lưới, nút, hoặc bản ghi cần kiểm tra. Hãy giảm số lượng đối tượng trong tệp, sau đó gửi lại.

    Hãy sửa yêu cầu, rồi gửi lại. Xem Lỗi.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra tiêu đề Authorization.

  • Name
    402 - Payment Required
    Description

    Ví dụ:

    • Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt giới hạn tín dụng. Hãy kiểm tra số dư tín dụng của bạn, rồi thử lại.
    • Gói miễn phí: Việc tạo tác vụ yêu cầu gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, rồi thử lại.
  • Name
    403 - Forbidden
    Description

    input_task_id là một mô hình chạm nổi (bas-relief), mà endpoint này không thể chuyển đổi. Thông báo là This model type does not support this operation. Hãy gửi một mô hình khác.

  • Name
    404 - Not Found
    Description

    input_task_id không khớp với bất kỳ tác vụ nào của bạn. Hãy kiểm tra ID tác vụ, rồi gửi lại yêu cầu.

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ. Hãy đợi, rồi thử lại. Xem Giới hạn tốc độ.

GET/openapi/v1/convert/:id

Lấy tác vụ Chuyển đổi

Trả về một tác vụ Chuyển đổi theo ID của nó.

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

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

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

DELETE/openapi/v1/convert/:id

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

Xóa vĩnh viễn một tác vụ Chuyển đổi, bao gồm các mô hình và dữ liệu của nó. Bạn không thể hoàn tác việc xóa.

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

Tham số đường dẫn

  • Name
    id
    Type
    path
    Description

    ID của tác vụ cần xóa.

Trạng thái tác vụ

Việc xóa một tác vụ PENDING sẽ hoàn lại tín dụng đã sử dụng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn lại tín dụng cho một tác vụ đã bắt đầu, vì vậy việc xóa nó sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi nó đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, sau đó mới xóa nó.

Việc xóa một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) sẽ không hoàn lại tín dụng.

Giá trị trả về

200 OK khi tác vụ được xóa, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

GET/openapi/v1/convert

List Convert tasks

Trả về danh sách các tác vụ Chuyển đổi của bạn.

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

Tham số

  • Name
    page_num
    Type
    integer
    mặc định 1
    Description

    Số trang cần trả về, tối đa 255. Giá trị lớn hơn sẽ trả về 400.

  • Name
    page_size
    Type
    integer
    mặc định 10
    Description

    Số lượng tác vụ trên mỗi trang, tối đa 100.

  • Name
    sort_by
    Type
    string
    Description

    Thứ tự sắp xếp.

    Các giá trị khả dụng:

    • +created_at: cũ nhất trước
    • -created_at: mới nhất trước

Giá trị trả về

Một danh sách phân trang các đối tượng tác vụ Convert.

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

Stream một tác vụ Convert

Truyền (stream) các cập nhật của một tác vụ Convert dưới dạng Server-Sent Events (SSE).

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
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID của tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Một luồng (stream) các đối tượng tác vụ Convert dưới dạng Server-Sent Events.

Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, theo cùng định dạng mà endpoint Get trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường kết quả của nó chưa có giá trị.

Đối tượng task Convert

Một đối tượng task Convert mô tả một lần chuyển đổi định dạng của mô hình 3D. Nó lưu trữ trạng thái, progress, và các tệp mô hình khi task thành công.

Thuộc tính

  • Name
    id
    Type
    string
    Description

    ID của task. Hãy coi đây là một chuỗi mờ (opaque), và đừng phụ thuộc vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại task, luôn là convert.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống cho mô hình đã chuyển đổi, một URL cho mỗi định dạng tệp. Chỉ những định dạng trong target_formats mới có URL. Một định dạng bạn không yêu cầu sẽ không có key, thay vì có một chuỗi rỗng.

  • Name
    progress
    Type
    integer
    Description

    Mức độ hoàn thành của task, tính theo phần trăm. Giá trị là 0 cho đến khi task bắt đầu và 100 khi task thành công.

  • Name
    status
    Type
    string
    Description

    Trạng thái của task, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng task đứng trước task này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi task đang ở trạng thái PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Thời điểm task được tạo, tính bằng mili giây Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Thời điểm task bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi task bắt đầu.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm task kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho đến khi task kết thúc.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm các URL tải xuống của task hết hạn, tính bằng mili giây Unix. Giá trị là 0 cho đến khi task kết thúc.

  • Name
    texture_urls
    Type
    array
    Description

    URL tải xuống cho các bản đồ texture của mô hình, khi task thành công: một mảng các đối tượng, mỗi đối tượng cho một bộ texture. Mỗi đối tượng có một URL base_color, và cũng có thể có các URL metallic, roughness, normal, emission, và metallic_roughness. Giá trị là null cho đến khi task thành công, và là một mảng rỗng khi mô hình không có bản đồ texture nào.

  • Name
    task_error
    Type
    object
    Description

    Thông tin chi tiết về lỗi khi task thất bại. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng mà task đã sử dụng, là 1 đối với một task Convert. Giá trị là 0 đối với một task FAILED.