Hatalar

Bu kılavuzda, Meshy API ile çalışırken bir şeyler ters gittiğinde neler olduğunu ele alacağız.

İstek Hataları

Bu hatalar, API isteğiniz reddedildiğinde hemen döndürülür. Neyin 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 ayrıntıları 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 genel kategorisini belirtir. Yeniden deneme stratejinize karar vermek için bunu kullanın.

Hata Kodları

code alanı mevcut olduğunda, belirli ve eyleme geçirilebilir bir sorunu tanımlar. Aşağıda her hata kodu için tam başvuru yer almaktadır.

image_too_complex

Bu hata, giriş görseli veya prompt, 3D üretim modelinin işleyemeyeceği kadar geometrik olarak karmaşık bir konuyu tanımladığında oluşur.

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

• Küçük nesnelerden oluşan yoğun yığınlar (ör. meyve dolu bir kasa, kitap yığını)
• Karmaşık tekrarlayan desenler (ör. kafes yapıları, iskeleler, tel örgüler)
• Karmaşık bina yapıları (ör. çok sayıda penceresi ve balkonu olan çok katlı binalar)
• Tek bir konu yerine tek bir görselde birden fazla ayrı nesne

Çok karmaşık olma olasılığı yüksek giriş örnekleri:

Çözüm:

1. Her görsel için tek bir nesne kullanın. Model, tek ve net bir konuyla en iyi şekilde çalışır. Aynı görsele veya prompt'a birden fazla ayrı nesne eklemeyin.
2. Konunuzu basitleştirin. Ayrıntı düzeyini azaltın. Örneğin, düzinelerce çiçekle dolu bir vazo yerine basit bir vazo kullanın.
3. Sahne düzeyindeki prompt'lardan kaçının. Tüm binalar, şehir blokları, mobilyayla dolu iç mekanlar veya manzaralar büyük olasılıkla modelin kapasitesini aşacaktır. Bunun yerine tek bir nesneye odaklanın.
4. Yoğun tekrarlayan yapılardan kaçının. İskeleler, tel örgüler, kafes desenleri veya çok sayıda küçük öğeden oluşan yığınlar gibi konular yaygın tetikleyicilerdir.

model_missing_uv

Bu hata, enable_original_uv true olarak ayarlanmış şekilde doku uygulamak için bir model yüklediğinizde, ancak modelde UV koordinatları olmadığında oluşur. UV koordinatları, 2B bir dokunun modelinizin 3B yüzeyine nasıl sarılacağını tanımlar.

Çözüm:

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

• Modelinizin özgün UV yerleşimini korumanız gerekiyorsa (ör. hassas doku eşleme için özel dikiş yerleşimi): modelinizin geçerli UV koordinatları olmalıdır. Yüklemeden önce 3B yazılımınızın UV düzenleyicisinde UV'lerin mevcut olduğunu doğrulayın. STL dosyalarının UV verisi depolayamayacağını unutmayın; bu nedenle bunun yerine GLB, FBX veya OBJ kullanın.
• Belirli bir UV kontrolüne ihtiyacınız yoksa (veya emin değilseniz): enable_original_uv değerini atlayın ya da 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 olmaz.

model_insufficient_uv

Bu hata, bir modelin UV koordinatları olduğunda, ancak UV kapsamı kaliteli dokulandırma için çok küçük olduğunda oluşur. Bu durum genellikle, uygun bir açılım olmadan yer tutucu veya çökmüş UV'ler oluşturan 3D araçlardan dışa aktarılan modellerde görülür.

Çö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 küçük bir alana çökmek yerine UV alanına düzgün şekilde yayıldığından emin olun.
• Belirli bir UV kontrolüne ihtiyacınız yoksa: enable_original_uv değerini atlayın veya false olarak ayarlayın. Sistem otomatik olarak yeni bir UV yerleşimi oluşturacaktır. Bunun dezavantajı, orijinal dikiş yerleşiminizi kaybetmenizdir; ancak otomatik oluşturulan UV'ler dokulandırma için uygun kapsama sahip olacaktır.

invalid_input

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

Yaygın nedenler şunları içerir:

• Boş veya bozulmuş model dosyaları
• Desteklenmeyen dosya biçimi varyasyonları (ör. ASCII FBX dosyaları, meshopt ile sıkıştırılmış GLB)
• Yüklenen modelde geçerli 3D nesne bulunmaması (ör. dosyanın yalnızca armatürler, kameralar veya ışıklar içermesi)
• Güvenlik filtrelerinden geçmeyen içerik

Çözüm: Neyin yanlış gittiğine ilişkin ayrıntılar için message alanını kontrol edin. Girdi dosyalarınızın ve parametrelerinizin uç noktanın gereksinimleriyle eşleştiğini doğrulayın.

moderation_blocked

Bu hata, prompt'unuz veya referans görselleriniz yapay zeka güvenlik filtreleri tarafından reddedildiğinde oluşur. Filtre, hem metin prompt'unu hem de tüm referans görselleri birlikte değerlendirir.

Çözüm:

• Müstehcen veya hassas açıklamaları kaldırmak için metin prompt'unuzu yeniden ifade edin.
• Güvenlik filtrelerini tetikleyebilecek içerik gösteriyorlarsa referans görselleri ayarlayın.

timeout

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

Çözüm:

1. İsteği yeniden deneyin. timeout'lar genellikle geçicidir ve yeniden deneme başarılı olabilir.
2. Girdinizi basitleştirin. Yeniden denemeler başarısız olmaya devam ederse girdiniz fazla karmaşık olabilir. Görüntünüzdeki veya prompt'unuzdaki ayrıntı düzeyini azaltmayı deneyin. Hangi girdi türlerinin işlenmesinin daha zor olduğuna dair rehberlik için image_too_complex bölümüne bakın.

format_conversion_failed

Bu hata, oluşturulan 3D model istediğiniz çıktı biçimine dönüştürülemediğinde oluşur. Model başarıyla oluşturuldu, ancak dönüştürme adımı başarısız oldu.

Çözüm:

1. İsteği yeniden deneyin.
2. Farklı bir çıktı biçimi deneyin. Belirli bir biçim sürekli başarısız oluyorsa, ihtiyaçlarınıza uygun başka bir biçime geçin.

En İyi Uygulamalar

1. Yeniden deneme mantığı uygulayın. timeout ve service_unavailable hataları için üstel geri çekilmeli yeniden deneme mantığı uygulayın.
2. Görev ID'lerini günlüğe kaydedin. Hata ayıklama amacıyla görev ID'sini her zaman günlüğe kaydedin. Destekle iletişime geçerken bunu ekleyin.
3. Girdileri doğrulayın. Göndermeden önce girdi görsellerinizin ve modellerinizin biçim gereksinimlerini karşıladığından emin olun.