UV açma API'si

UV açma API'si, mevcut bir 3D model için otomatik olarak yüksek kaliteli bir UV açma oluşturur. Dokulandırmadan önce ön koşul adımı olarak veya aşağı akış araçları (Blender, Substance Painter, Unreal) için temiz, çakışmayan bir UV yerleşimine ihtiyaç duyduğunuz her zaman kullanın.

Çıktı bir "UV beyaz model"dir — girdiyle aynı şekle sahiptir ancak yepyeni UV koordinatları vardır ve gerçek doku içermez (glTF malzeme yuvasını geçerli tutmak için 2×2 gri bir yer tutucu malzeme dahil edilmiştir; standart araçlar bunu dokusuz olarak ele alır).

Sınırlamalar. Auto UV şu anda en fazla 40.000 yüz içeren ağları destekler — daha büyük modeller 400 ile reddedilir; poligon sayısını azaltmak için önce Yeniden ağ çalıştırın. Dörtgen ve n-gon ağlar UV oluşturma sırasında üçgenleştirilir, bu nedenle çıktı her zaman bir üçgen ağdır.

POST/openapi/v1/uv-unwrap

UV açma Görevi Oluşturun

Bu uç nokta yeni bir UV açma görevi oluşturur.

Parametreler

input_task_id veya model_url değerlerinden tam olarak biri gereklidir. İkisi de sağlanırsa, input_task_id öncelik alır.

Name
input_task_id
Type
string
Zorunlu
Description
UV açma uygulamak istediğiniz GLB çıktısına sahip tamamlanmış bir Meshy API görevinin ID'si (örneğin bir Görselden 3D'ye, Metinden 3D'ye veya Yeniden ağ sonucu). Kaynak görevin durumu SUCCEEDED olmalı ve bir GLB dosyası üretmiş olmalıdır.
Kaynak ağ 40.000 yüzlük yüz sayısı üst sınırını aşarsa, istek 400 ile reddedilir ve poligon sayısını düşürmek için önce Yeniden ağ çalıştırmalısınız.

Name
model_url
Type
string
Zorunlu
Description
Herkese açık olarak erişilebilen bir URL veya data URI aracılığıyla doğrudan bir 3D model sağlayın. Yalnızca .glb desteklenir — API glTF ikili biçimini okur ve diğer biçimleri ayrıştırmaz. Başka bir biçimdeki (.fbx, .obj, .stl, .gltf) bir modele UV açma uygulamak için, önce Dönüştür API aracılığıyla onu .glb biçimine dönüştürün, ardından ortaya çıkan görev ID'sini input_task_id olarak veya GLB çıktı URL'sini burada iletin.
Data URI'ler için MIME type olarak application/octet-stream kullanın.
input_task_id için geçerli olan aynı 40.000 yüzlük üst sınır burada da geçerlidir: aşırı büyük ağlar 400 ile reddedilir — önce Yeniden ağ çalıştırın.

Dönenler

Yanıtın result özelliği, yeni oluşturulan UV açma görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- Eksik parametre: input_task_id veya model_url sağlanmalıdır.
- Geçersiz girdi görevi: input_task_id, GLB sonucu olan başarılı bir göreve başvurmalıdır.
- Yüz sayısı aşıldı: Kaynak ağ, UV açma üst sınırından daha fazla yüze sahip. Önce Yeniden ağ çalıştırın.
- Geçersiz model biçimi: model_url, desteklenmeyen bir uzantıya sahip bir dosyayı işaret ediyor.
- Erişilemeyen URL: model_url indirilemedi.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yetersiz kredi. UV açma çağrı başına 5 kredi tutar.
Name
404 - Not Found
Description
Özellik hesabınız için etkin değil. UV açma, kullanıma sunma sırasında bir Statsig bayrağıyla sınırlandırılmıştır — erişime ihtiyacınız varsa Meshy destek ekibiyle iletişime geçin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

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

Bir UV açma Görevini Al

Bu uç nokta, bir UV açma görevinin mevcut durumunu ID'ye göre alır.

Döndürür

Bir UV açma Görevi nesnesi döndürür.

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

Aşağıdaki örnek görev nesnesine bakın.

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

Bir UV açma Görevini Sil

Bir UV açma görevini kalıcı olarak silin. Görev ve çıktıları erişilemez hale gelir.

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 açma Görevlerini Listele

Çağıranın UV açma görevlerinin sayfalanmış bir listesini, en yeniler önce olacak şekilde döndürür. page_num ve page_size ile standart sayfalama.

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

Bir UV açma Görevini Akış Olarak İzleme

Görev progress'ine Server-Sent Events olarak abone olun. Her message olayı bir UV açma Görev nesnesi taşır; görev SUCCEEDED, FAILED veya CANCELED durumuna ulaştığında akış kapanır.

Tamamlanmada daha düşük gecikme için GET /openapi/v1/uv-unwrap/:id yoklaması yapmak yerine bunu kullanın.

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 Açma Görev Nesnesi

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı.
Name
type
Type
string
Description
Her zaman uv-unwrap.
Name
model_urls
Type
object
Description
Oluşturulan UV beyaz model için önceden imzalanmış indirme URL'leri. UV açma her zaman tek bir glb girdisi döndürür — çıktı, girdi geometrisini korur, yeni UV koordinatlarını uygular ve herhangi bir doku yerine varsayılan gri malzeme kullanır.
Name
thumbnail_url
Type
string
Description
UV beyaz modelin PNG önizlemesi için önceden imzalanmış URL.
Name
progress
Type
integer
Description
Görev progress değeri, 0 ile 100 arasında.
Name
status
Type
string
Description
PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biri.
Name
preceding_tasks
Type
integer
Description
Bu görevden önce kuyrukta bekleyen görev sayısı. Durum PENDING iken mevcuttur.
Name
created_at
Type
timestamp
Description
Görev oluşturma zaman damgası, milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
İşlemenin başladığı zaman damgası, milisaniye cinsinden. Başlayana kadar 0.
Name
finished_at
Type
timestamp
Description
Tamamlanma zaman damgası, milisaniye cinsinden. Tamamlanana kadar 0.
Name
expires_at
Type
timestamp
Description
İmzalı indirme URL'lerinin süresinin dolacağı zaman damgası, milisaniye cinsinden.
Name
task_error
Type
object
Description
Başarısız görevler için hata ayrıntıları. Tam task_error nesne başvurusu için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi. FAILED görevleri için 0 döndürür (krediler başarısızlık durumunda iade edilir). UV açma başarılı olduğunda 5 kredi ücretlendirir.

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
}