UV Unwrap API
為現有的 3D 模型產生 UV 展開。請在為模型加上 texture 之前執行此任務，或者當 Blender、Substance Painter 或 Unreal 等工具需要一個乾淨、無重疊的 UV 配置時執行此任務。
輸出結果是一個 UV 白模。它與輸入模型的形狀相同，擁有全新的 UV 座標，且不含真實的 texture。它包含一個 2×2 的灰色佔位 material，以確保 glTF 的 material 插槽保持有效，標準工具會將其視為未上色的模型。
UV Unwrap 支援最多 40,000 個面的 mesh。更大的模型將回傳 400。如需減少面數，請先執行 Remesh。
Meshy 會在產生 UV 的過程中對四邊形與 n 邊形 mesh 進行三角化處理，因此輸出結果始終是三角形 mesh。
建立 UV Unwrap 任務
建立一個 UV Unwrap 任務。
任務會在背景執行。關於任務通常需要多長時間，請參閱處理時間。
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"
}
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
除非你傳送
model_url，否則此項為必填。要進行 UV 展開的 Meshy API 任務的 ID（其 GLB 輸出將被解包），例如 Image to 3D、Text to 3D 或 Remesh 任務。該任務的狀態必須為SUCCEEDED，並已產生 GLB 檔案。該 mesh 最多可包含 40,000 個面。面數超過該值的 mesh 將回傳
400。要減少面數，請先執行 Remesh。
- Name
- model_url
- Type
- string
- 必選
- Description
除非你傳送
input_task_id，否則此項為必填。要解包的模型，可以是公開 URL 或 Data URI。如果兩者都傳送，Meshy 將使用input_task_id。模型必須是
.glb檔案。要解包其他格式，請先使用 Convert API 將其轉換為 GLB。透過
http或httpsURL 提供的檔案最大為 400 MB，作為 Data URI 時最大為 100 MB。對於 Data URI，請使用 MIME typeapplication/octet-stream。超過 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 結果的成功 API 任務。 - 面數超限：該 mesh 的面數超過了 UV Unwrap 所允許的上限。請先執行 Remesh。
- 模型格式無效：
model_url檔案的副檔名不受支援。 - URL 無法存取：Meshy 無法下載
model_url檔案。 - 模型檔案過大：
model_url檔案透過http或httpsURL 提供時超過 400 MB，或作為 Data URI 時超過 100 MB。 - 面數過多：
model_url檔案超過 100 MB，且面數超過 10,000,000。請減少面數後重新傳送檔案。 - 模型檔案不可讀：
model_url檔案超過 100 MB，且 Meshy 無法讀取其檔案標頭。例如，這是一個經過 Draco 壓縮的 GLB。 - 模型標頭過於複雜：
model_url檔案超過 100 MB，且其檔案標頭中包含過多的 mesh、節點或記錄，無法完成檢查。請減少檔案中的物件數量後重新傳送。
請修正請求後重新傳送。參見 Errors。
- 缺少參數：既未傳送
- Name
401 - Unauthorized- Description
API key 缺失或無效。請檢查
Authorization請求標頭。
- Name
402 - Payment Required- Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行該任務，或帳戶已達到積分限額。一個 UV Unwrap 任務消耗 5 積分。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在你的訂閱設定中升級你的方案，然後重試。
- Name
403 - Forbidden- Description
input_task_id是一個浮雕模型，此 endpoint 無法對其進行 UV 展開。訊息為This model type does not support this operation。請傳送其他模型。
- Name
404 - Not Found- Description
input_task_id與你的任何任務都不相符。請檢查任務 ID，然後重新傳送請求。
- Name
429 - Too Many Requests- Description
你已超出速率限制。請稍候後重試。參見速率限制。
取得 UV Unwrap 任務
根據 ID 回傳某個 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 任務
永久刪除一個 UV Unwrap 任務，包括其輸出結果。刪除操作無法復原。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
任務狀態
刪除 PENDING 狀態的任務會退還建立該任務時使用的積分。
IN_PROGRESS 狀態的任務無法被刪除。該請求會回傳 409 Conflict，
任務會繼續執行。Meshy 不會為已經開始的任務退還積分，
因此刪除它會讓你同時損失積分和結果。請等待任務
變為 SUCCEEDED、FAILED 或 CANCELED 狀態後再進行刪除。
刪除處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務
不會退還其積分。
列出 UV Unwrap 任務
回傳您的 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 任務進度
以伺服器發送事件（SSE）的形式串流傳輸 UV Unwrap 任務的更新。每個 message 事件都會攜帶一個 UV Unwrap 任務物件。當任務達到 SUCCEEDED、FAILED 或 CANCELED 狀態時，串流會關閉。
如果想更早得知任務已完成，請使用此 endpoint，而不是輪詢 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 任務物件
一個 UV Unwrap 任務物件描述了一次 3D 模型的 UV 展開。它保存了任務的狀態、progress，以及任務成功時的模型檔案。
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。請將其視為一個不透明的字串，不要依賴其格式。
- 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
任務建立的時間，單位為 Unix 毫秒。
- Name
- started_at
- Type
- timestamp
- Description
任務開始的時間，單位為 Unix 毫秒。在任務開始之前為
0。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成的時間，單位為 Unix 毫秒。在任務完成之前為
0。
- Name
- expires_at
- Type
- timestamp
- Description
簽署下載 URL 過期的時間，單位為 Unix 毫秒。
- Name
- task_error
- Type
- object
- Description
任務失敗時的錯誤詳情。參見錯誤。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數量。一次成功的 UV Unwrap 任務消耗 5 個積分。對於
FAILED的任務，該值為0，因為 Meshy 會在任務失敗時退還積分。