UV Unwrap API
UV Unwrap API 可為現有的 3D 模型自動生成高品質的 UV 展開。可將其用作貼圖 texture 之前的前置步驟——或在任何需要為下游工具（Blender、Substance Painter、Unreal）提供乾淨、無重疊的 UV 布局時使用。
輸出結果是一個「UV 白模」——與輸入模型形狀相同，但帶有全新的 UV 座標，且沒有真實 texture（為保持 glTF material 插槽有效，其中包含一個 2×2 的灰色占位 material；標準工具會將其視為未貼圖狀態）。
限制。 Auto UV 目前支援最多 40,000 個面 的 mesh——更大的模型會被拒絕並返回 400；請先執行 Remesh 以降低面數。四邊形和 N 邊形 mesh 會在 UV 生成過程中被三角化，因此輸出結果始終為三角形 mesh。
創建 UV Unwrap 任務
此 endpoint 用於創建一個新的 UV Unwrap 任務。
該任務會在背景執行。關於通常需要多長時間，請參閱處理時間。
參數
input_task_id 或 model_url 兩者必須且只能提供其中一個。如果兩者都提供，則 input_task_id 具有更高的優先順序。
- Name
- input_task_id
- Type
- string
- 必選
- Description
你希望進行 UV-unwrap 的、已完成的 Meshy API 任務的 ID，該任務的 GLB 輸出將作為處理對象（例如 Image to 3D、Text to 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-unwrap，請先透過 Convert API 將其轉換為.glb，然後將生成的任務 ID 作為input_task_id傳入，或在此處傳入其 GLB 輸出的 URL。對於 Data URI，請使用 MIME type
application/octet-stream。最大檔案大小：
http或httpsURL 為 400 MB，data:URI 為 100 MB。超過 100 MB 的 GLB 不得使用 Draco 壓縮。與
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指向的檔案。 - 模型檔案過大：
model_url檔案超過了 400 MB（http或httpsURL）或 100 MB（data:URI）的限制。 - 面數過多：
model_url檔案超過 100 MB，且面數超過 10,000,000。請減少面數後重新傳送檔案。 - 模型檔案無法讀取：
model_url檔案超過 100 MB，且其檔案標頭無法讀取，例如經過 Draco 壓縮的 GLB。 - 模型檔案標頭過於複雜：
model_url檔案超過 100 MB，且其檔案標頭中包含過多需要檢查的 mesh、節點或記錄。請減少檔案中的物件數量後重新傳送。
- 缺少參數：必須提供
- Name
401 - Unauthorized- Description
身份驗證失敗。請檢查你的 API 金鑰。
- Name
402 - Payment Required- Description
積分不足，無法執行此任務。UV Unwrap 每次呼叫花費 5 積分。
- Name
404 - Not Found- Description
你的帳戶未啟用此功能。UV Unwrap 在灰度發布期間由 Statsig 開關控制 —— 如需取得權限，請聯絡 Meshy 支援團隊。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# 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"
}
獲取 UV Unwrap 任務
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
請參見下方的任務物件範例。
刪除一個 UV Unwrap 任務
永久刪除一個 UV Unwrap 任務。該任務及其輸出結果將變得無法存取。
仍處於 PENDING 狀態的任務會被刪除，並退還創建時消耗的積分。
已處於 IN_PROGRESS 狀態的任務無法被刪除：該請求會被拒絕並返回 409 Conflict，任務會繼續執行。worker 已經開始處理的任務所消耗的積分是不可退還的，因此在執行過程中刪除它會使你同時失去積分和結果。請等待任務進入 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。
處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務會被刪除，且不會退還積分。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
List UV Unwrap Tasks
返回呼叫者的 UV Unwrap 任務的分頁列表，按最新順序排列。透過 page_num 和 page_size 進行標準分頁。
Request
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
訂閱 UV Unwrap 任務進度
以 Server-Sent Events 的方式訂閱任務 progress。每個 message 事件都攜帶一個UV Unwrap 任務物件；當任務進入 SUCCEEDED、FAILED 或 CANCELED 狀態時，串流將關閉。
相比輪詢 GET /openapi/v1/uv-unwrap/:id，使用此方式可以在任務完成時獲得更低的延遲。
Request
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
任務創建的 timestamp，單位為毫秒。
- Name
- started_at
- Type
- timestamp
- Description
開始處理的 timestamp，單位為毫秒。開始前為
0。
- Name
- finished_at
- Type
- timestamp
- Description
完成的 timestamp，單位為毫秒。完成前為
0。
- Name
- expires_at
- Type
- timestamp
- Description
簽署下載 URL 失效的 timestamp，單位為毫秒。
- Name
- task_error
- Type
- object
- Description
失敗任務的錯誤詳情。完整的
task_error物件參考請參閱 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
此任務消耗的積分。對於
FAILED的任務返回0（失敗時會退還積分）。UV Unwrap 成功後扣除 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
}