API Trải UV

API Trải UV tự động tạo một bản Trải UV chất lượng cao cho mô hình 3D hiện có. Sử dụng nó như bước tiên quyết trước khi tạo 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 lấn cho các công cụ downstream (Blender, Substance Painter, Unreal).

Đầu ra là một "mô hình trắng UV" — cùng hình dạng với đầu vào nhưng có 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 slot vật liệu glTF hợp lệ; các công cụ tiêu chuẩn xem đây là chưa có texture).

Giới hạn. Auto UV hiện hỗ trợ lưới tối đa 40.000 mặt — các mô hình lớn hơn sẽ bị từ chối với 400; hãy chạy Remesh trước để giảm số đa giác. Lưới quad và n-gon được tam giác hóa 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

Tạo tác vụ Trải UV

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

Tham số

Cần cung cấp đúng một trong hai input_task_id hoặc model_url. Nếu cung cấp cả hai, input_task_id 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 tất mà bạn muốn Trải UV đầu ra GLB của tác vụ đó (ví dụ: kết quả Ả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 tệp GLB.

    Nếu lưới nguồn vượt quá giới hạn số mặt tối đa 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 trực tiếp một mô hình 3D qua URL có thể truy cập công khai hoặc Data URI. Chỉ hỗ trợ .glb — API đọc glTF dạng nhị phân và không phân tích các định dạng khác. Để Trải UV một mô hình ở định dạng khác (.fbx, .obj, .stl, .gltf), trước tiên hãy chuyển đổi nó sang .glb qua API Chuyển đổi, 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 tác vụ đó tại đây.

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

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

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.

Chế độ lỗi

  • Name
    400 - Bad Request
    Description

    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 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 (mesh) nguồn có nhiều mặt hơn 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 truy cập được: Không thể tải xuống model_url.
  • Name
    401 - Unauthorized
    Description

    Xác thực không thành công. 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 cho 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 được kiểm soát bởi cờ Statsig trong quá trình triển khai — hãy liên hệ bộ phận hỗ trợ 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 độ của mình.

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 theo 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ụ bên dưới.

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.

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

Liệt kê các tác vụ Trải UV

Trả về danh sách được 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 thông 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

Truyền phát một tác vụ Trải UV

Đăng ký nhận progress của tác vụ dưới dạng Server-Sent Events. Mỗi sự kiện message mang theo một đối tượng tác vụ Trải UV; luồng sẽ đóng khi tác vụ đạt đến SUCCEEDED, FAILED hoặc CANCELED.

Sử dụng cách này thay vì thăm dò GET /openapi/v1/uv-unwrap/:id để có độ trễ thấp hơn khi hoàn tất.

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 tác vụ Trải UV

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Luôn là uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống được ký sẵn cho mô hình trắng UV đã tạo. 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 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ý sẵn tới bản xem trước PNG của mô hình trắng UV.

  • Name
    progress
    Type
    integer
    Description

    progress của tác vụ, từ 0 đến 100.

  • Name
    status
    Type
    string
    Description

    Một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng tác vụ được xếp hàng trước tác vụ này. Hiển thị khi trạng thái là PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    Dấu thời gian sau đó các URL tải xuống đã 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 tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Tín dụng (credits) được tác vụ này tiêu thụ. Trả về 0 cho các tác 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.

Example UV Unwrap Task Object

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