UV Unwrap API

UV Unwrap API 會為既有的 3D 模型自動生成高品質的 UV 展開。它通常作為貼圖前的預處理步驟——或者在你需要將模型匯出到 Blender、Substance Painter、Unreal 等下游工具繼續處理時，提供一份乾淨、無重疊的 UV 版面配置。

輸出是一個「UV 白模」——形狀與輸入一致，但帶有全新的 UV 座標，並使用一個 2×2 灰色佔位材質（用於維持 glTF 材質插槽合法；標準工具會將它視為無紋理）。

限制說明。 Auto UV 目前僅支援 40,000 面以內的模型——超過會返回 400，請先使用重構網格 降低面數。四邊形 / 多邊形（quad / n-gon）網格會在生成 UV 時被三角化，因此輸出一律為三角網格。

POST/openapi/v1/uv-unwrap

建立 UV Unwrap 任務

建立新的 UV Unwrap 任務。

參數

input_task_id 與 model_url 二選一必填。如果兩者都傳，會以 input_task_id 為準。

  • Name
    input_task_id
    Type
    string
    必選
    Description

    想要進行 UV 展開的 Meshy API 任務 ID（例如一個已完成的影象生成 3D、文字生成 3D 或重構網格 任務）。來源任務的狀態必須為 SUCCEEDED，且必須產出過 GLB 檔案。

    如果來源模型的面數超過 40,000 面上限，請求會返回 400，請先呼叫重構網格 降低面數。

  • Name
    model_url
    Type
    string
    必選
    Description

    透過公開可存取的 URL 或 Data URI 直接提供一個 3D 模型。僅支援 .glb —— 本介面只讀取 glTF binary，不解析其他格式。如需對其他格式（.fbx、.obj、.stl、.gltf）進行 UV 展開，請先透過 Convert API 轉成 .glb，再將轉換出的 task ID 作為 input_task_id 傳入，或者將轉換產物的 GLB URL 作為本欄位傳入。

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

    與 input_task_id 一樣適用 40,000 面上限：超限模型會返回 400，請先使用重構網格 降低面數。

回傳值

回應的 result 欄位是新建 UV Unwrap 任務的 id。

錯誤碼

  • Name
    400 - Bad Request
    Description

    請求不合法。常見原因：

    • 缺少參數：input_task_id 或 model_url 至少要傳一個。
    • 來源任務無效：input_task_id 必須指向一個 SUCCEEDED 且有 GLB 產物的任務。
    • 面數超限：來源模型面數超過 UV Unwrap 上限，請先使用重構網格。
    • 格式不支援：model_url 指向的檔案副檔名不在支援清單中。
    • URL 無法存取：model_url 無法下載。
  • Name
    401 - Unauthorized
    Description

    驗證失敗，請檢查 API key。

  • Name
    402 - Payment Required
    Description

    積分不足。UV Unwrap 每次消耗 5 積分。

  • Name
    404 - Not Found
    Description

    目前帳號尚未啟用此功能。UV Unwrap 在灰階期間透過 Statsig flag 控制，如需開通請聯絡 Meshy 支援。

  • Name
    429 - Too Many Requests
    Description

    超過速率限制。

请求

POST
/openapi/v1/uv-unwrap
# 链式调用：基于已有的 Meshy 任务
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"
    }'

# 或者通过公开 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"
    }'

响应

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

取得 UV Unwrap 任務

依 ID 查詢 UV Unwrap 任務的目前狀態。

回傳值

返回一個 UV Unwrap Task 物件。

请求

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 任務及其產物——刪除後任務及輸出檔案皆無法存取。

请求

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）。

请求

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 訂閱任務進度。每個 message 事件都會帶有一個 UV Unwrap Task 物件；當任務進入 SUCCEEDED、FAILED 或 CANCELED 後，串流會自動關閉。

相較於輪詢 GET /openapi/v1/uv-unwrap/:id，串流取得在任務結束時延遲更低。

请求

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——產物保留輸入幾何、替換 UV 座標，並使用一個預設灰色材質代替原貼圖。

  • 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

    在目前任務前方排隊的任務數。僅在 status 為 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

    失敗任務的錯誤詳情。完整欄位請參考 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    該任務消耗的積分。失敗任務返回 0（失敗會自動退款）。UV Unwrap 成功時收取 5 積分。

示例 UV Unwrap Task 对象

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