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

Bir 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'den tam olarak biri gereklidir. Her ikisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
GLB çıktısını UV açmak istediğiniz tamamlanmış bir Meshy API görevinin kimliği (örneğin Görselden 3D'ye, Metinden 3D'ye veya Yeniden ağ sonucu). Kaynak görevin SUCCEEDED durumunda olması ve bir GLB dosyası üretmiş olması gerekir.
Eğer kaynak ağ 40.000 yüz tavanını aşarsa, istek 400 ile reddedilir ve önce poligon sayısını düşürmek için Yeniden ağ çalıştırmalısınız.

Name
model_url
Type
string
Zorunlu
Description
Doğrudan herkese açık bir URL veya veri URI'si aracılığıyla bir 3D model sağlayın. Yalnızca .glb desteklenir — API glTF ikili dosyasını okur ve diğer formatları çözümlemez. Başka bir formatta (.fbx, .obj, .stl, .gltf) bir modeli UV açmak için, önce Dönüştür API aracılığıyla .glb'ye dönüştürün, ardından ortaya çıkan görev kimliğini input_task_id olarak veya GLB çıktı URL'sini buraya iletin.
Veri URI'leri için MIME type application/octet-stream kullanın.
input_task_id için geçerli olan aynı 40.000 yüz tavanı burada da geçerlidir: aşırı büyük ağlar 400 ile reddedilir — önce Yeniden ağ çalıştırın.

Dönüşler

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

Başarısızlık Modları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- Eksik parametre: input_task_id veya model_url'den biri sağlanmalıdır.
- Geçersiz giriş görevi: input_task_id, GLB sonucu olan başarılı bir göreve referans vermelidir.
- Yüz sayısı aşıldı: Kaynak ağ, UV açma tavanından daha fazla yüze sahiptir. Önce Yeniden ağ çalıştırın.
- Geçersiz model formatı: model_url, desteklenmeyen bir uzantıya sahip bir dosyaya işaret ediyor.
- Ulaşılamaz 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 yeterli krediniz yok. UV açma, çağrı başına 5 kredi maliyetindedir.
Name
404 - Not Found
Description
Özellik hesabınız için etkinleştirilmemiş. UV açma, rollout sırasında bir Statsig bayrağı ile sınırlandırılmıştır — erişime ihtiyacınız varsa Meshy desteği ile iletişime geçin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

İstek

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

Yanıt

{
  "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 silin. Görev ve çıktıları erişilemez hale gelir.

İstek

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
}