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ợ

API Trải UV

Tạo bản trải UV cho một mô hình 3D có sẵn. Chạy tác vụ này trước khi bạn lên texture cho mô hình, hoặc khi một công cụ như Blender, Substance Painter, hay Unreal cần một bố cục UV sạch, không chồng chéo.

Đầu ra là một mô hình trắng UV. Nó có hình dạng giống hệt đầu vào, tọa độ UV mới, và không có texture thực sự. Nó bao gồm một vật liệu giữ chỗ màu xám 2×2 để khe vật liệu glTF luôn hợp lệ, và các công cụ tiêu chuẩn sẽ coi nó là chưa được lên texture.

Trải UV hỗ trợ lưới có tối đa 40.000 mặt. Một mô hình lớn hơn sẽ trả về 400. Để giảm số lượng mặt, hãy chạy Remesh trước.

Meshy sẽ tam giác hóa các lưới dạng tứ giác và đa giác trong quá trình tạo UV, vì vậy đầu ra luôn là một lưới tam giác.

POST/openapi/v1/uv-unwrap

Tạo tác vụ UV Unwrap

Tạo một tác vụ UV Unwrap.

Tác vụ này chạy ngầm. Để biết thời gian thường cần cho một tác vụ, xem Thời gian xử lý.

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

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ụ Meshy API có đầu ra GLB mà bạn muốn trải UV, ví dụ như tác vụ Ảnh sang 3D, Văn bản sang 3D, hoặc Remesh. Tác vụ phải có trạng thái SUCCEEDED và đã tạo ra một tệp GLB.

    Lưới có thể có tối đa 40.000 mặt. Một lưới có nhiều hơn số đó sẽ trả về 400. Để giảm số lượng mặt, hãy chạy Remesh trước.

  • 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 trải UV, 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. Để trải UV một định dạng khác, hãy chuyển đổi nó sang GLB bằng Convert API trước.

    Tệp có thể tối đa 400 MB nếu 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 GLB trên 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 như với input_task_id. Một lưới có nhiều hơn số đó sẽ trả về 400, vì vậy hãy chạy Remesh trước.

Giá trị trả về

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

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

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

    • Thiếu tham số: Không gửi input_task_id lẫn model_url.
    • 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ết quả GLB.
    • Vượt quá số lượng mặt: Lưới có nhiều mặt hơn giới hạn cho phép của UV Unwrap. Hãy chạy Remesh trước.
    • Đị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 từ model_url.
    • Tệp mô hình quá lớn: Tệp model_url vượt quá 400 MB nếu 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ó nhiều hơn 10.000.000 mặt. Hãy giảm số lượng mặt, rồi 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à Meshy không thể đọc phần header của nó. Ví dụ, đây là một tệp 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, node, hoặc bản ghi cần kiểm tra. Hãy giảm số lượng đối tượng trong tệp, rồi 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

    Thiếu hoặc không hợp lệ khóa API. Hãy kiểm tra header 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. Một tác vụ UV Unwrap tốn 5 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ô hình phù điêu (bas-relief), mà endpoint này không thể trải UV. 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/uv-unwrap/:id

Lấy tác vụ UV Unwrap

Trả về trạng thái hiện tại của một tác vụ Trải UV theo ID của nó.

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 ví dụ về phản hồi, hãy tham khảo ví dụ về đối tượng tác vụ UV Unwrap.

Giá trị trả về

Đối tượng tác vụ UV Unwrap.

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

Xóa tác vụ UV Unwrap

Xóa vĩnh viễn một tác vụ UV Unwrap, bao gồm cả các đầu ra của nó. Bạn không thể hoàn tác việc xó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}"

Trạng thái tác vụ

Việc xóa một tác vụ PENDING sẽ hoàn lại số 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 tín dụng cho một tác vụ đã bắt đầu chạy, 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 đến khi nó đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, rồi mới xóa.

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.

GET/openapi/v1/uv-unwrap

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

Trả về danh sách phân trang các tác vụ Trải UV của bạn, mới nhất trước. Để duyệt qua danh sách, hãy sử dụng 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

Stream một tác vụ Trải UV

Stream các cập nhật của một tác vụ Trải UV dưới dạng Server-Sent Events (SSE). Mỗi sự kiện message mang theo một đối tượng tác vụ Trải UV. Luồng stream sẽ đóng lại khi tác vụ đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED.

Để biết sớm hơn khi nào tác vụ hoàn tất, hãy sử dụng endpoint này thay vì liên tục gọi (poll) GET /openapi/v1/uv-unwrap/:id.

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

Một đối tượng tác vụ Trải UV mô tả một lần trải UV của một mô hình 3D. Nó lưu trữ trạng thái, progress, và tệp mô hình khi tác vụ 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
}
  • Name
    id
    Type
    string
    Description

    ID của tác vụ. Hãy coi đây là một chuỗi không minh bạch, và đừng phụ thuộc vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại tác vụ, luôn là uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL tải xuống có chữ ký cho mô hình trắng UV. Trải UV luôn trả về một khóa glb duy nhất. Mô hình giữ nguyên hình học đầu vào, có tọa độ UV mới, và sử dụng vật liệu xám mặc định thay vì texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL tải xuống có chữ ký cho hình ảnh xem trước PNG của mô hình trắng UV.

  • Name
    progress
    Type
    integer
    Description

    Mức độ hoàn thành của tác vụ, tính theo phần trăm từ 0 đến 100.

  • Name
    status
    Type
    string
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Có mặt khi tác vụ đang ở trạng thái PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm các URL tải xuống có chữ ký hết hạn, tính bằng mili giây Unix.

  • Name
    task_error
    Type
    object
    Description

    Chi tiết lỗi khi tác vụ thất bại. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng mà tác vụ đã sử dụng. Một tác vụ Trải UV thành công tốn 5 tín dụng. Giá trị là 0 đối với tác vụ FAILED, vì Meshy hoàn lại tín dụng khi tác vụ thất bại.