Hatalar

Bu kılavuzda, Meshy API ile çalışırken bir şeyler ters gittiğinde ne olacağını konuşacağız.

İstek Hataları

Bu hatalar, API isteğiniz reddedildiğinde hemen döndürülür. Ne yanlış gittiğini anlamak için HTTP durum kodunu ve message alanını kontrol edin.

{
  "message": "Invalid model file extension: .3dm"
}

Görev Hataları

Bu hatalar, bir görev oluşturulduktan ve işlenirken meydana gelir. Hata detayları için görev yanıtındaki task_error nesnesini kontrol edin.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Hata Türleri

type alanı, hatanın geniş kategorisini belirtir. Tekrar deneme stratejinizi belirlemek için bunu kullanın.

Hata Kodları

code alanı mevcut olduğunda, belirli ve uygulanabilir bir sorunu tanımlar. Aşağıda her hata kodu için tam referans bulunmaktadır.

image_too_complex

Bu hata, giriş resmi veya prompt'un 3D üretim modelinin işlemesi için geometrik olarak çok karmaşık bir konuyu tanımladığında meydana gelir.

Yaygın örnekler şunları içerir:

• Küçük nesnelerden oluşan yoğun yığınlar (örneğin, meyve dolu bir kasa, kitap yığını)
• Karmaşık tekrar eden desenler (örneğin, kafes yapılar, iskeleler, tel örgüler)
• Karmaşık bina yapıları (örneğin, birçok pencere ve balkona sahip çok katlı binalar)
• Tek bir konu yerine bir görüntüde birden fazla farklı nesne

Muhtemelen çok karmaşık olan giriş örnekleri:

Çözüm:

1. Her resimde tek bir nesne kullanın. Model, tek bir net konuyla en iyi şekilde çalışır. Aynı resimde veya prompt'ta birden fazla ayrı nesne bulundurmayın.
2. Konunuzu basitleştirin. Detay seviyesini azaltın. Örneğin, onlarca çiçekle dolu bir vazo yerine basit bir vazo.
3. Sahne düzeyinde prompt'lardan kaçının. Tüm binalar, şehir blokları, mobilyalarla dolu iç mekanlar veya manzaralar modelin kapasitesini aşabilir. Bunun yerine tek bir nesneye odaklanın.
4. Yoğun tekrar eden yapılardan kaçının. İskeleler, tel örgüler, kafes desenler veya birçok küçük öğeden oluşan yığınlar gibi konular yaygın tetikleyicilerdir.

model_missing_uv

Bu hata, enable_original_uv ayarı true olarak ayarlanmış bir modeli doku için yüklediğinizde, ancak modelin UV koordinatları olmadığında ortaya çıkar. UV koordinatları, bir 2D dokunun modelinizin 3D yüzeyine nasıl sarıldığını tanımlar.

Çözüm:

Doğru çözüm, enable_original_uv ayarını neden true olarak ayarladığınıza bağlıdır:

• Modelinizin orijinal UV yerleşimini korumanız gerekiyorsa (örneğin, hassas doku eşlemesi için özel dikiş yerleştirme): modelinizin geçerli UV koordinatlarına sahip olması gerekir. Yüklemeden önce 3D yazılımınızın UV düzenleyicisinde UV'lerin varlığını doğrulayın. STL dosyalarının UV verilerini depolayamayacağını unutmayın, bu nedenle GLB, FBX veya OBJ kullanın.
• Belirli bir UV kontrolüne ihtiyacınız yoksa (veya emin değilseniz): enable_original_uv'yi atlayın veya false olarak ayarlayın. Sistem, modeliniz için otomatik olarak bir UV yerleşimi oluşturacaktır. Otomatik oluşturulan UV'ler kapsama için optimize edilmiştir, ancak doku dikişlerinin nereye yerleştirileceği üzerinde kontrolünüz olmayacaktır.

model_insufficient_uv

Bu hata, bir modelin UV koordinatlarına sahip olduğu, ancak UV kapsamının kaliteli dokulama için çok küçük olduğu durumlarda meydana gelir. Bu genellikle, uygun bir açılım olmadan yer tutucu veya çökmüş UV'ler üreten 3D araçlardan dışa aktarılan modellerde olur.

Çözüm:

• Orijinal UV yerleşiminizi korumanız gerekiyorsa: modelin UV'lerini 3D yazılımınızda yeniden açın. UV adalarının UV alanı boyunca düzgün bir şekilde yayıldığından ve küçük bir alana sıkıştırılmadığından emin olun.
• Belirli bir UV kontrolüne ihtiyacınız yoksa: enable_original_uv'i atlayın veya false olarak ayarlayın. Sistem otomatik olarak yeni bir UV yerleşimi oluşturacaktır. Dezavantajı, orijinal dikiş yerleşiminizi kaybetmenizdir, ancak otomatik oluşturulan UV'ler dokulama için uygun kapsama sahip olacaktır.

invalid_input

Bu, girdi doğrulamadan geçemediğinde ancak daha spesifik bir kod uygulanmadığında kullanılan yedek hata kodudur. message alanı, hatanın belirli nedenini içerir.

Yaygın nedenler şunlardır:

• Boş veya bozulmuş model dosyaları
• Desteklenmeyen dosya formatı varyasyonları (örneğin, ASCII FBX dosyaları, meshopt-sıkıştırılmış GLB)
• Yüklenen modelde geçerli 3D nesneler bulunmaması (örneğin, dosya yalnızca iskeletler, kameralar veya ışıklar içeriyor)
• Güvenlik filtrelerinden geçemeyen içerik

Çözüm: Ne yanlış gittiğine dair ayrıntılar için message alanını kontrol edin. Girdi dosyalarınızın ve parametrelerinizin uç noktanın gereksinimlerine uygun olduğundan emin olun.

moderation_blocked

Bu hata, prompt veya referans görsellerinizin AI güvenlik filtreleri tarafından reddedildiğinde meydana gelir. Filtre, hem metin prompt'unu hem de referans görsellerini birlikte değerlendirir.

Çözüm:

• İma edici veya hassas tanımlamaları kaldırmak için metin prompt'unuzu yeniden ifade edin.
• Güvenlik filtrelerini tetikleyebilecek içerikler gösteriyorsa referans görsellerini ayarlayın.

timeout

Bu hata, görevinizin işleme süresinin izin verilen sınırı aştığı anlamına gelir. Bu, sistem yükünün yüksek olması veya girdinin zaman sınırı içinde işlenemeyecek kadar karmaşık olması nedeniyle meydana gelebilir.

Çözüm:

1. İsteği yeniden deneyin. Zaman aşımı genellikle geçicidir ve yeniden deneme başarılı olabilir.
2. Girdinizi basitleştirin. Yeniden denemeler başarısız olmaya devam ederse, girdiniz çok karmaşık olabilir. Görselinizdeki veya prompt'unuzdaki detay seviyesini azaltmayı deneyin. İşlenmesi daha zor olan girdi türleri hakkında rehberlik için image_too_complex bölümüne bakın.

format_conversion_failed

Bu hata, oluşturulan 3D modelin istenen çıktı formatına dönüştürülemediğinde meydana gelir. Model başarıyla oluşturuldu, ancak dönüştürme adımı başarısız oldu.

Çözüm:

1. İsteği tekrar deneyin.
2. Farklı bir çıktı formatı deneyin. Belirli bir format sürekli olarak başarısız oluyorsa, ihtiyaçlarınıza uygun başka bir formata geçin.

En İyi Uygulamalar

1. Yeniden deneme mantığını uygulayın. timeout ve service_unavailable hataları için üstel geri çekilme yeniden deneme mantığını uygulayın.
2. Görev kimliklerini kaydedin. Hata ayıklama amacıyla her zaman görev kimliğini kaydedin. Destekle iletişime geçerken bunu dahil edin.
3. Girdileri doğrulayın. Girdi resimlerinizin ve modellerinizin gönderimden önce format gereksinimlerini karşıladığından emin olun.