UV Açma API'si

Mevcut bir 3D model için UV açma işlemi gerçekleştirin. Modeli dokulandırmadan önce veya Blender, Substance Painter ya da Unreal gibi bir araç temiz, üst üste binmeyen bir UV yerleşimi gerektirdiğinde bunu çalıştırın.

Çıktı bir UV beyaz modeldir. Girdiyle aynı şekle, yeni UV koordinatlarına sahiptir ve gerçek bir dokusu yoktur. glTF malzeme yuvasının geçerli kalması için 2×2 gri yer tutucu bir malzeme içerir ve standart araçlar bunu dokusuz olarak değerlendirir.

UV Açma, 40.000 yüze kadar ağları destekler. Daha büyük bir model 400 döndürür. Yüz sayısını azaltmak için önce Yeniden ağ çalıştırın.

Meshy, UV oluşturma sırasında dörtgen ve n-gon ağları üçgenlere dönüştürür, bu nedenle çıktı her zaman bir üçgen ağdır.

POST/openapi/v1/uv-unwrap

UV açma görevi oluşturun

Bir UV açma görevi oluşturur.

Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü hakkında bilgi için bkz. İşlem süreleri.

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

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
model_url göndermediğiniz sürece zorunludur. UV'sini açmak istediğiniz GLB çıktısına sahip bir Meshy API görevinin kimliği; örneğin bir Görselden 3D'ye, Metinden 3D'ye veya Yeniden ağ görevi. Görevin durumu SUCCEEDED olmalı ve bir GLB dosyası üretmiş olmalıdır.
Ağ en fazla 40.000 yüzeye sahip olabilir. Daha fazlasına sahip bir ağ 400 döndürür. Yüzey sayısını azaltmak için önce Yeniden ağ çalıştırın.

Name
model_url
Type
string
Zorunlu
Description
input_task_id göndermediğiniz sürece zorunludur. UV'si açılacak model; genel bir URL veya bir data URI olarak. Her ikisini de gönderirseniz Meshy input_task_id'yi kullanır.
Model bir .glb dosyası olmalıdır. Başka bir formatı açmak için önce Dönüştür API ile GLB'ye dönüştürün.
Dosya bir http veya https URL'sinden en fazla 400 MB, data URI olarak ise en fazla 100 MB olabilir. Data URI için application/octet-stream MIME type'ını kullanın. 100 MB'den büyük bir GLB, Draco sıkıştırması kullanmamalıdır.
input_task_id için geçerli olan aynı 40.000 yüzey sınırı burada da geçerlidir. Daha fazlasına sahip bir ağ 400 döndürür, bu yüzden önce Yeniden ağ çalıştırın.

Dönüş değerleri

Yanıtın result alanı, yeni UV açma görevinin kimliğini tutar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik parametre: Ne input_task_id ne de model_url gönderildi.
- Geçersiz giriş görevi: input_task_id, GLB sonucuna sahip başarılı bir API görevi değil.
- Yüzey sayısı aşıldı: Ağ, UV açmanın izin verdiğinden daha fazla yüzeye sahip. Önce Yeniden ağ çalıştırın.
- Geçersiz model formatı: model_url dosyası desteklenmeyen bir uzantıya sahip.
- Ulaşılamayan URL: Meshy, model_url dosyasını indiremiyor.
- Model dosyası çok büyük: model_url dosyası, bir http veya https URL'sinden 400 MB'nin üzerinde, ya da data URI olarak 100 MB'nin üzerinde.
- Çok fazla yüzey: model_url dosyası 100 MB'nin üzerinde ve 10.000.000'dan 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'nin üzerinde ve Meshy başlığını okuyamıyor. Örneğin, Draco ile sıkıştırılmış bir GLB olabilir.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'nin üzerinde ve başlığında kontrol edilecek çok fazla ağ, düğüm veya kayıt var. Dosyadaki nesne sayısını azaltın, ardından tekrar gönderin.
İsteği düzeltin, ardından tekrar gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı. Bir UV açma görevi 5 kredi tutar. Kredi bakiyenizi kontrol edin, ardından tekrar deneyin.
- Ücretsiz plan: Görev oluşturmak için ücretli bir plan gerekir. Planınızı abonelik ayarlarınızdan yükseltin, ardından tekrar deneyin.
Name
403 - Forbidden
Description
input_task_id, bu uç noktanın UV'sini açamayacağı bir kabartma modelidir. Mesaj This model type does not support this operation şeklindedir. Farklı bir model gönderin.
Name
404 - Not Found
Description
input_task_id, görevlerinizden hiçbiriyle eşleşmiyor. Görev kimliğini kontrol edin, ardından isteği tekrar gönderin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyin, ardından tekrar deneyin. Bkz. Hız sınırları.

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

Bir UV açma görevini al

Bir UV açma görevinin mevcut durumunu ID'siyle 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}"

Örnek bir yanıt için örnek UV açma görevi nesnesine bakın.

Dönüş Değerleri

UV açma görevi nesnesi.

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

Bir UV açma görevini sil

Bir UV açma görevini, çıktıları dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döner ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu yüzden görevi silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

GET/openapi/v1/uv-unwrap

UV Açma görevlerini listele

En yeniden en eskiye doğru sıralanmış, sayfalanmış bir UV Açma görevleri listesi döndürür. Liste içinde sayfalar arasında gezinmek için page_num ve page_size parametrelerini kullanın.

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

UV açma görevini akışla izleme

Bir UV açma görevinin güncellemelerini Server-Sent Events (SSE) olarak akışla iletir. Her message olayı bir UV açma görevi nesnesi taşır. Görev SUCCEEDED, FAILED veya CANCELED durumuna ulaştığında akış kapanır.

Görevin tamamlandığını daha erken öğrenmek için, GET /openapi/v1/uv-unwrap/:id uç noktasını yoklamak yerine bu uç noktayı 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

Bir UV açma görev nesnesi, bir 3D modelin UV açma işlemini tanımlar. Görev başarılı olduğunda durumu, progress'i ve model dosyasını içerir.

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
Görev kimliği. Bunu anlaşılmaz bir dize olarak kabul edin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman uv-unwrap.
Name
model_urls
Type
object
Description
UV beyaz model için imzalı indirme URL'leri. UV açma her zaman tek bir glb anahtarı döndürür. Model, girdi geometrisini korur, yeni UV koordinatlarına sahiptir ve doku yerine varsayılan gri bir malzeme kullanır.
Name
thumbnail_url
Type
string
Description
UV beyaz modelin PNG önizleme görüntüsü için imzalı indirme URL'si.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, 0 ile 100 arasında bir yüzde olarak.
Name
status
Type
string
Description
Görev durumu; PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biri.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önceki görevlerin sayısı. Görev PENDING durumundayken mevcuttur.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0 değerindedir.
Name
finished_at
Type
timestamp
Description
Görevin bittiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir.
Name
expires_at
Type
timestamp
Description
İmzalı indirme URL'lerinin süresinin dolduğu zaman, Unix milisaniye cinsinden.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı. Başarılı bir UV açma görevi 5 kredi tutar. FAILED bir görev için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.