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

Tạo một Nhiệm vụ Trải UV

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

Tham số

Chính xác 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 API đã hoàn thành mà bạn muốn Trải UV (ví dụ như kết quả của Ảnh sang 3D, Văn bản sang 3D, hoặc Remesh). Nhiệm 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.

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

    Cung cấp một mô hình 3D trực tiếp qua URL công khai hoặc Data URI. Chỉ hỗ trợ .glb — API đọc glTF 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), chuyển đổi nó sang .glb trước qua Convert API, sau đó truyền ID nhiệm vụ kết quả làm input_task_id hoặc URL đầu ra GLB của nó ở đây.

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

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

Trả về

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

Các chế độ thất bại

  • Name
    400 - Bad Request
    Description

    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 input_task_id hoặc model_url.
    • 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 với kết quả GLB.
    • Số mặt vượt quá: Lưới nguồn có nhiều mặt hơn giới hạn Trải UV. 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: model_url không thể tải xuống.
  • 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 nhiệm 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 không được kích hoạt cho tài khoản của bạn. Trải UV được kiểm soát bởi một cờ Statsig trong quá trình triển khai — liên hệ với hỗ trợ Meshy nếu bạn cầ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.

Yêu cầu

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

Phản hồi

{
  "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 kết quả của nó sẽ không thể truy cập được.

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
}