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.

API Trải UV

API Trải UV tự động tạo ra một trải UV chất lượng cao cho một mô hình 3D hiện có. Sử dụng nó như bước tiền đề trước khi áp dụng texture — hoặc bất cứ khi nào bạn cần một bố cục UV sạch, không chồng chéo cho các công cụ hạ nguồn (Blender, Substance Painter, Unreal).

Kết quả đầu ra là một "mô hình trắng UV" — cùng hình dạng với đầu vào nhưng với tọa độ UV hoàn toàn mới và không có texture thực (một vật liệu giữ chỗ màu xám 2×2 được bao gồm để giữ cho khe vật liệu glTF hợp lệ; các công cụ tiêu chuẩn coi đây là chưa được áp dụng texture).

Giới hạn. Auto UV hiện hỗ trợ lưới lên đến 40,000 mặt — các mô hình lớn hơn sẽ bị từ chối với mã 400; chạy Remesh trước để giảm số đa giác. Lưới tứ giác và n-gon được chia tam giác trong quá trình tạo UV, vì vậy đầu ra luôn là lưới tam giác.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

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

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

Tham số

Cần cung cấp chính xác một trong hai: input_task_id hoặc model_url. 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 API đã hoàn thành mà bạn muốn Trải UV cho đầu ra GLB của nó (ví dụ như kết quả của Ảnh sang 3D, Văn bản sang 3D, hoặc Remesh). Tác vụ nguồn phải có trạng thái SUCCEEDED và đã tạo ra một tệp GLB.

    Nếu lưới nguồn vượt quá giới hạn số mặt là 40.000 mặt, yêu cầu sẽ bị từ chối với mã 400 và bạn nên chạy Remesh trước để giảm số đa giác xuống.

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

    Cung cấp một mô hình 3D trực tiếp qua một URL có thể truy cập công khai hoặc data URI. Chỉ hỗ trợ .glb — API chỉ đọc glTF nhị phân và không phân tích các định dạng khác. Để Trải UV cho một mô hình ở định dạng khác (.fbx, .obj, .stl, .gltf), hãy chuyển đổi nó sang .glb trước thông qua Convert API, sau đó truyền ID tác vụ kết quả dưới dạng input_task_id hoặc URL đầu ra GLB của nó tại đây.

    Đối với Data URI, sử dụng MIME type application/octet-stream.

    Kích thước tệp tối đa: 400 MB cho URL http hoặc https, 100 MB cho data: URI. Một GLB vượt quá 100 MB không được sử dụng nén Draco.

    Giới hạn 40.000 mặt tương tự cũng áp dụng cho input_task_id: các lưới quá khổ sẽ bị từ chối với mã 400 — hãy chạy Remesh trước.

Giá trị trả về

Thuộc tính result của phản hồi chứa id của tác vụ Trải UV vừa được tạo.

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

  • Name
    400 - Bad Request
    Description

    Yêu cầu không hợp lệ. Các nguyên nhân phổ biến:

    • Thiếu tham số: Phải cung cấp input_task_id hoặc model_url.
    • 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 có kết quả GLB.
    • Vượt quá số mặt: Lưới nguồn có số mặt vượt quá giới hạn của Trải UV. Hãy chạy Remesh trước.
    • Đị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.
    • Tệp mô hình quá lớn: Tệp model_url vượt quá 400 MB (URL http hoặc https) hoặc 100 MB (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ố mặt, sau đó gửi lại tệp.
    • Tệp mô hình không đọc được: Tệp model_url vượt quá 100 MB và không thể đọc được phần header của nó, ví dụ như một GLB đã nén Draco.
    • 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.
  • Name
    401 - Unauthorized
    Description

    Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.

  • Name
    402 - Payment Required
    Description

    Không đủ tín dụng để thực hiện tác vụ này. Trải UV tốn 5 tín dụng mỗi lần gọi.

  • Name
    404 - Not Found
    Description

    Tính năng này chưa được bật cho tài khoản của bạn. Trải UV đang được kiểm soát bởi một cờ Statsig trong quá trình triển khai — vui lòng liên hệ bộ phận hỗ trợ của Meshy nếu bạn cần quyền truy cập.

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ.

Request

POST
/openapi/v1/uv-unwrap
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

Truy xuất một tác vụ Trải UV

Endpoint này truy xuất trạng thái hiện tại của một tác vụ Trải UV bằng ID.

Trả về

Trả về một đối tượng Tác vụ Trải UV.

Request

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Xem đối tượng tác vụ ví dụ dưới đây.

DELETE/openapi/v1/uv-unwrap/:id

Xóa một Tác vụ Trải UV

Xóa vĩnh viễn một tác vụ Trải UV. Tác vụ và các đầu ra của nó sẽ không thể truy cập được nữa.

Một tác vụ vẫn đang ở trạng thái PENDING sẽ bị 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 không thể bị 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 nó đạ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.

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap

Danh sách các tác vụ Trải UV

Trả về danh sách phân trang các tác vụ Trải UV của người gọi, mới nhất trước. Phân trang tiêu chuẩn qua page_num và page_size.

Request

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

Phát trực tuyến một Tác vụ Trải UV

Đăng ký tiến trình tác vụ dưới dạng Sự kiện Gửi từ Máy chủ. Mỗi sự kiện message mang theo một đối tượng Tác vụ Trải UV; luồng sẽ đóng lại khi tác vụ đạt đến SUCCEEDED, FAILED, hoặc CANCELED.

Sử dụng điều này thay vì thăm dò GET /openapi/v1/uv-unwrap/:id để giảm độ trễ khi hoàn thành.

Request

GET
/openapi/v1/uv-unwrap/:id/stream
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

Đối Tượng Nhiệm Vụ Trải UV

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Luôn là uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống được ký trước cho mô hình trắng UV được tạo ra. Trải UV luôn trả về một mục glb duy nhất — đầu ra giữ nguyên hình học đầu vào, thay thế bằng tọa độ UV mới và sử dụng vật liệu màu xám mặc định thay cho bất kỳ texture nào.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL được ký trước đến bản xem trước PNG của mô hình trắng UV.

  • Name
    progress
    Type
    integer
    Description

    Tiến độ nhiệm vụ, từ 0 đến 100.

  • Name
    status
    Type
    string
    Description

    Một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng nhiệm vụ xếp hàng trước nhiệm vụ này. Có mặt khi trạng thái là PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Dấu thời gian tạo nhiệm vụ, tính bằng mili giây.

  • Name
    started_at
    Type
    timestamp
    Description

    Dấu thời gian khi xử lý bắt đầu, tính bằng mili giây. 0 cho đến khi bắt đầu.

  • Name
    finished_at
    Type
    timestamp
    Description

    Dấu thời gian hoàn thành, tính bằng mili giây. 0 cho đến khi hoàn thành.

  • Name
    expires_at
    Type
    timestamp
    Description

    Dấu thời gian sau đó các URL tải xuống được ký sẽ hết hạn, tính bằng mili giây.

  • Name
    task_error
    Type
    object
    Description

    Chi tiết lỗi cho các nhiệm vụ thất bại. Xem Lỗi để tham khảo đầy đủ đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Tín dụng tiêu thụ bởi nhiệm vụ này. Trả về 0 cho các nhiệm vụ FAILED (tín dụng được hoàn lại khi thất bại). Trải UV tính phí 5 tín dụng khi thành công.

Ví Dụ Đối Tượng Nhiệm Vụ Trải UV

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}