UV Açma API

UV Açma API'si, mevcut bir 3D model için otomatik olarak yüksek kaliteli bir UV açma işlemi oluşturur. Doku uygulamadan önce veya aşağı akış araçları (Blender, Substance Painter, Unreal) için temiz, çakışmayan bir UV yerleşimi gerektiğinde ön koşul adımı olarak kullanın.

Çıktı, "UV beyaz model"dir — girişle aynı şekildedir ancak yepyeni UV koordinatları ile gerçek bir doku içermez (glTF malzeme yuvasını geçerli tutmak için 2×2 gri bir yer tutucu malzeme dahildir; standart araçlar bunu dokusuz olarak kabul eder).

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

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

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

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü görmek için bkz. İşleme Süreleri.

Parametreler

input_task_id veya model_url parametrelerinden tam olarak biri gereklidir. Her ikisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
UV açmak istediğiniz GLB çıktısına sahip, tamamlanmış bir Meshy API görevinin kimliği (ö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üzey ü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ırmanız gerekir.

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 binary'yi okur ve diğer biçimleri ayrıştırmaz. Başka bir biçimdeki (.fbx, .obj, .stl, .gltf) bir modeli UV açmak için önce Dönüştür API aracılığıyla .glb biçimine dönüştürün, ardından oluşan görev kimliğini input_task_id olarak ya da onun GLB çıktı URL'sini burada geçirin.
Data URI'ler için application/octet-stream MIME type'ını kullanın.
Maksimum dosya boyutu: http veya https URL için 400 MB, data: URI için 100 MB. 100 MB'ı aşan bir GLB, Draco sıkıştırması kullanmamalıdır.
input_task_id için geçerli olan aynı 40.000 yüzey ü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öndürülenler

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 edilemedi. Yaygın nedenler:
- Eksik parametre: input_task_id veya model_url parametrelerinden biri sağlanmalıdır.
- Geçersiz girdi görevi: input_task_id, GLB sonucuna sahip başarılı bir görevi işaret etmelidir.
- Yüzey sayısı aşıldı: Kaynak ağ, UV açma üst sınırından daha fazla yüzeye sahip. Önce Yeniden ağ çalıştırın.
- Geçersiz model biçimi: model_url, desteklenmeyen bir uzantıya sahip bir dosyayı gösteriyor.
- Erişilemeyen URL: model_url indirilemedi.
- Model dosyası çok büyük: model_url dosyası 400 MB'ı (http veya https URL) veya 100 MB'ı (data: URI) aşıyor.
- Çok fazla yüzey: model_url dosyası 100 MB'ın üzerinde ve 10.000.000'den fazla yüzeye sahip. Yüzey sayısını azaltın, ardından dosyayı tekrar gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'ın üzerinde ve başlığı okunamıyor, örneğin Draco sıkıştırmalı bir GLB.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'ın üzerinde ve başlığı kontrol edilemeyecek kadar çok ağ, düğüm veya kayıt içeriyor. Dosyadaki nesne sayısını azaltın, ardından tekrar gönderin.
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 işlemi, çağrı başına 5 kredi tutar.
Name
404 - Not Found
Description
Bu özellik hesabınız için etkinleştirilmemiş. UV açma, kullanıma sunulma sürecinde bir Statsig bayrağı ile 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 Getir

Bu uç nokta, bir UV açma görevinin mevcut durumunu kimlik ile getirir.

Döndürülenler

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

İstek

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 siler. Görev ve çıktıları artık erişilemez hale gelir.

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan krediler iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlattığı bir görevin kredileri iade edilemez, bu nedenle çalışma sırasında silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Nihai bir durumda (SUCCEEDED, FAILED veya CANCELED) olan bir görev iade yapılmadan silinir.

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, en yenisi ilk olacak şekilde sayfalı listesini 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 Yayınla

Görev progress durumunu Sunucu Tarafından Gönderilen Olaylar olarak takip edin. Her message olayı bir UV açma Görev nesnesi taşır; görev SUCCEEDED, FAILED veya CANCELED durumuna ulaştığında yayın kapanır.

Tamamlanma süresini kısaltmak için GET /openapi/v1/uv-unwrap/:id sorgulaması yerine bunu kullanın.

İstek

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 girişi döndürür — çıktı, giriş geometrisini korur, yeni UV koordinatları ekler 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 ilerlemesi, 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örevin önünde sırada bekleyen görev sayısı. Durum PENDING iken mevcut.
Name
created_at
Type
timestamp
Description
Görev oluşturulma zaman damgası, milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
İşlemin başladığı zaman damgası, milisaniye cinsinden. Başlamadan önce 0.
Name
finished_at
Type
timestamp
Description
Tamamlanma zaman damgası, milisaniye cinsinden. Tamamlanmadan önce 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 detayları. Tam task_error nesne referansı için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen krediler. FAILED görevler için 0 döner (başarısızlık durumunda krediler iade edilir). UV Açma başarıyla tamamlandığında 5 kredi alır.

Örnek UV Açma Görev Nesnesi

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