UV Unwrap API

UV Unwrap API 可為現有 3D 模型自動產生高品質的 UV 展開。請在貼圖處理之前的準備步驟中使用它——或者在任何需要為下游工具（Blender、Substance Painter、Unreal）產生乾淨、無重疊的 UV 佈局時使用。

輸出結果是一個「UV 白模」——形狀與輸入模型相同，但擁有全新的 UV 座標，且不含真實 texture（其中包含一個 2×2 灰色佔位 material，以保持 glTF material 插槽有效；標準工具會將其視為未貼圖狀態）。

限制說明。 Auto UV 目前支援最多 40,000 個面 的 mesh——更大的模型將回傳 400 錯誤；請先執行 Remesh 以降低 polycount。四邊面和多邊面 mesh 在 UV 生成過程中會被三角化，因此輸出始終為三角形 mesh。

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

此 endpoint 用於建立一個新的 UV Unwrap 任務。

參數

input_task_id 和 model_url 中必須且只能提供其中一個。如果兩者都提供了，則 input_task_id 優先。

  • Name
    input_task_id
    Type
    string
    必選
    Description

    一個已完成的 Meshy API 任務的 ID，你希望對其 GLB 輸出進行 UV 展開（例如 Image to 3D、Text to 3D 或 Remesh 的結果）。來源任務的狀態必須為 SUCCEEDED，並且已產生 GLB 檔案。

    如果來源 mesh 的面數超過 40,000 面的上限，請求將被拒絕並回傳 400，此時你應先執行 Remesh 以降低 polycount。

  • Name
    model_url
    Type
    string
    必選
    Description

    透過一個公開可存取的 URL 或 data URI 直接提供一個 3D 模型。僅支援 .glb —— 該 API 只讀取 glTF 二進位格式，不會解析其他格式。如果要對其他格式（.fbx、.obj、.stl、.gltf）的模型進行 UV 展開，請先透過 Convert API 將其轉換為 .glb，然後將得到的任務 ID 作為 input_task_id 傳入，或在此處傳入其 GLB 輸出的 URL。

    對於 Data URI，請使用 MIME type application/octet-stream。

    與 input_task_id 相同的 40,000 面上限同樣適用：超大的 mesh 會被拒絕並回傳 400 —— 請先執行 Remesh。

回傳值

回應中的 result 屬性包含新建立的 UV Unwrap 任務的 id。

失敗模式

  • Name
    400 - Bad Request
    Description

    請求不可接受。常見原因：

    • 缺少參數：必須提供 input_task_id 或 model_url 中的一個。
    • 無效的輸入任務：input_task_id 必須指向一個具有 GLB 結果的成功任務。
    • 面數超限：來源 mesh 的面數超過了 UV Unwrap 的上限。請先執行 Remesh。
    • 無效的模型格式：model_url 指向的檔案副檔名不受支援。
    • 無法存取的 URL：無法下載 model_url 指向的內容。
  • Name
    401 - Unauthorized
    Description

    身份驗證失敗。請檢查你的 API key。

  • Name
    402 - Payment Required
    Description

    credits 不足以執行此任務。UV Unwrap 每次呼叫花費 5 credits。

  • Name
    404 - Not Found
    Description

    你的帳戶未啟用此功能。UV Unwrap 在發布期間受 Statsig 標誌控制 —— 如需存取權限，請聯絡 Meshy 支援團隊。

  • Name
    429 - Too Many Requests
    Description

    你已超出速率限制。

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

獲取一個 UV Unwrap 任務

此 endpoint 透過 ID 獲取 UV Unwrap 任務的目前狀態。

回傳值

回傳一個 UV Unwrap 任務物件。

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

請參見下方的範例任務物件。

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

刪除 UV Unwrap 任務

永久刪除一個 UV Unwrap 任務。該任務及其輸出結果將變得無法存取。

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

獲取 UV Unwrap 任務列表

回傳呼叫者的 UV Unwrap 任務的分頁列表，按最新排序。透過 page_num 和 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

串流獲取 UV Unwrap 任務

以伺服器發送事件（Server-Sent Events）的方式訂閱任務的 progress。每個 message 事件都攜帶一個 UV Unwrap Task object；當任務達到 SUCCEEDED、FAILED 或 CANCELED 狀態時，該串流將關閉。

使用該介面代替輪詢 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

UV Unwrap 任務物件

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。

  • Name
    type
    Type
    string
    Description

    始終為 uv-unwrap。

  • Name
    model_urls
    Type
    object
    Description

    產生的 UV 白模的預簽章下載 URL。UV Unwrap 始終回傳單一 glb 項目——輸出結果保留輸入的 geometry，替換為全新的 UV 座標，並使用預設的灰色 material 代替任何 texture。

  • Name
    thumbnail_url
    Type
    string
    Description

    UV 白模的 PNG 預覽的預簽章 URL。

  • Name
    progress
    Type
    integer
    Description

    任務進度，從 0 到 100。

  • Name
    status
    Type
    string
    Description

    取值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。

  • Name
    preceding_tasks
    Type
    integer
    Description

    排在此任務之前的排隊任務數量。僅在狀態為 PENDING 時存在。

  • Name
    created_at
    Type
    timestamp
    Description

    任務建立的時間戳，單位為毫秒。

  • Name
    started_at
    Type
    timestamp
    Description

    開始處理的時間戳，單位為毫秒。在開始之前為 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    完成的時間戳，單位為毫秒。在完成之前為 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    簽章下載 URL 過期的時間戳，單位為毫秒。

  • Name
    task_error
    Type
    object
    Description

    失敗任務的錯誤詳情。完整的 task_error 物件參考請參見Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    此任務消耗的 credits。對於 FAILED 任務回傳 0（失敗時會退還 credits）。UV Unwrap 成功時收取 5 credits。

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
}