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 以降低面數。四邊形和多邊形（n-gon）mesh 會在 UV 產生過程中被 三角化，因此輸出結果始終是三角形 mesh。

POST/openapi/v1/uv-unwrap

建立 UV 展開任務

此端點用於建立一個新的 UV 展開任務。

參數

input_task_id 或 model_url 中必須且只能提供一個。如果兩者都提供，則 input_task_id 優先順序較高。

  • Name
    input_task_id
    Type
    string
    必選
    Description

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

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

  • 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 展開任務的 id。

失敗模式

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

    積分不足，無法執行此任務。UV 展開每次呼叫花費 5 積分。

  • Name
    404 - Not Found
    Description

    你的帳戶未啟用此功能。在推出期間，UV 展開受 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 展開任務

此端點透過 ID 取得某個 UV 展開任務的目前狀態。

回傳值

回傳一個 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}"

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

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

刪除 UV 展開任務

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

仍處於 PENDING 狀態的任務會被刪除，且建立時消耗的 積分會被退還。

已處於 IN_PROGRESS 狀態的任務無法刪除：請求會被拒絕並回傳 409 Conflict，任務將繼續執行。工作進程已經開始處理的任務，其 積分無法退還，因此在執行過程中刪除它將使你同時失去積分 和結果。請等待其到達 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務會被刪除， 且不會退還積分。

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

List UV Unwrap Tasks

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

以伺服器發送事件（Server-Sent Events）的方式訂閱任務 progress。每個 message 事件都會攜帶一個 UV 展開任務物件；一旦任務到達 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 展開任務物件

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。

  • Name
    type
    Type
    string
    Description

    始終為 uv-unwrap。

  • Name
    model_urls
    Type
    object
    Description

    產生的 UV 白模的預簽章下載 URL。UV 展開始終回傳單一 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

    此任務消耗的積分。對於 FAILED 任務回傳 0（失敗時會退還積分）。UV 展開在成功時收取 5 個積分。

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
}