Hatalar

Bu kılavuzda, Meshy API ile çalışırken bir şeyler ters gittiğinde neler olduğundan bahsedeceğiz.

İ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 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 genel kategorisini belirtir. Yeniden deneme stratejinize karar vermek 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.

model_missing_texture

Bu hata, bir Multi-Color Print görevinin girdi modelinde, dönüştürücünün baskı renklerine ayırabileceği hiçbir renk bilgisi bulunmadığında oluşur. Çok renkli bir 3MF, modelin renklerinden oluşturulur; bu yüzden düz beyaz bir ağ — örneğin hiç dokulanmamış bir Text to 3D veya Görselden 3D'ye önizlemesi ya da onarılmış / otomatik bölünmüş bir çıktı — üzerinde çalışılacak hiçbir şey barındırmaz.

Neyin renk kaynağı sayılacağı, istediğiniz style değerine bağlıdır:

• realistic, temel renk dokusunu modelin UV'leri üzerinden örnekler; bu nedenle her ağ parçasında UV koordinatlarına sahip tek bir temel renk dokusu gerektirir.
• cartoon, renkleri yüzey başına düzleştirir ve herhangi bir parça üzerinde temel renk dokusunu veya vertex başına renkleri (COLOR_0) kabul eder.

Ne temel renk dokusu ne de vertex renkleri bulunan bir model her iki stil için de reddedilir; aksi takdirde cartoon ile bu durum tek renkli bir baskı olarak "başarılı" sayılırdı.

Çoğu istek, görev oluşturulmadan önce reddedilir (aynı açıklamayla birlikte 400 Bad Request), bu yüzden bu kodu genellikle yalnızca girdinin önceden incelenemediği durumlarda görürsünüz — örneğin bir .fbx yüklemesi, görev bunu normalleştirdikten sonra kontrol edilir.

Çözüm:

• Önce modeli dokulayın. Model üzerinde bir Yeniden dokulama görevi çalıştırın veya dokulama etkinleştirilmiş şekilde oluşturun (bir Text to 3D refine görevi veya should_texture: true içeren bir Görselden 3D'ye görevi) ve bu görevi input_task_id olarak iletin.
• Vertex renkli modeller (fotogrametri taramaları, elle boyanmış ağlar): COLOR_0 değerini okuyan style: "cartoon" isteğinde bulunun.
• realistic altında kısmen dokulanmış veya çoklu dokulu modeller: her ağ parçasının UV'lere ve aynı, tek bir temel renk dokusuna ihtiyacı vardır. Kalan parçaları dokulayın veya dokuları tek bir atlasta birleştirin, ya da style: "cartoon"'a geçin.

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'unuzun veya referans görsellerinizin yapay zeka güvenlik filtreleri tarafından reddedilmesi durumunda oluşur. Filtre, metin prompt'unu ve varsa referans görselleri birlikte değerlendirir.

Çözüm:

• Müstehcen veya hassas tanımlamaları kaldırmak için metin prompt'unuzu yeniden ifade edin.
• Güvenlik filtrelerini tetikleyebilecek içerikler barındırıyorsa referans görselleri düzenleyin.

moderation_unavailable

Bu hata, içerik moderation'ının geçici olarak kullanılamaması nedeniyle görevin kontrol yapılmadan çalıştırılmak yerine başarısız olması durumunda oluşur. İçeriğinizde herhangi bir sorun yoktur. type değeri server_error'dır.

Çözüm: Görevi yeniden oluşturun.

timeout

Bu hata, görevin işlenmesi veya kuyrukta bekleme süresinin sunucu tarafındaki zaman sınırını aşması anlamına gelir; bu nedenle görev başarısız olmuştur ve kredileri iade edilmiştir. Bu durum, sistemdeki yüksek yük nedeniyle veya girdinin zaman sınırı içinde işlenemeyecek kadar karmaşık olması nedeniyle ortaya çıkabilir.

Bu, kendi kodunuzdaki bir timeout'tan farklıdır. İstemciniz beklemeyi durdurduysa, görev hâlâ çalışıyor olabilir; bkz. Görev Yaşam Döngüsü.

Çözüm:

1. Görevi tekrar oluşturun. Timeout'lar genellikle geçicidir ve yeni bir görev başarılı olabilir.
2. Girdinizi basitleştirin. Yeniden denemeler başarısız olmaya devam ediyorsa, girdiniz çok karmaşık olabilir. Görselinizdeki veya promptunuzdaki ayrıntı düzeyini azaltmayı deneyin. Hangi tür girdilerin işlenmesinin daha zor olduğuna dair rehberlik için image_too_complex bölümüne bakın.

queue_timeout

Bu hata, görevin kuyrukta başlamadan çok uzun süre beklediği ve bu nedenle başarısız olduğu anlamına gelir; bunun için tahsil edilen kredi varsa iade edilmiştir. Bu sizin girdinizden kaynaklanmaz. type değeri timeout'tur.

Çözüm: Görevi tekrar oluşturun.

format_conversion_failed

Bu hata, oluşturulan 3D modelin istediğiniz çıktı formatına dönüştürülememesi durumunda meydana gelir. Model başarıyla oluşturulmuştur, ancak dönüştürme adımı başarısız olmuştur.

Çözüm:

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

En İyi Uygulamalar

1. Yeniden deneme mantığı uygulayın. Bir görev timeout, service_unavailable veya server_error hatasıyla başarısız olduğunda, üstel geri çekilme (exponential backoff) ile görevi yeniden oluşturun. Eğer başarısız olan kendi isteğinizin zaman aşımıysa, yeni bir görev oluşturmayın: önce mevcut olanı kontrol edin (bkz. Görev Yaşam Döngüsü).
2. Görev kimliklerini kaydedin. Hata ayıklama amacıyla görev kimliğini her zaman kaydedin. Destek ekibiyle iletişime geçerken bunu belirtin.
3. Girdileri doğrulayın. Girdi görsellerinizin ve modellerinizin gönderimden önce format gereksinimlerini karşıladığından emin olun.
4. API'yi sunucunuzdan çağırın. Bir tarayıcıda çalışan kod, API anahtarınızı sayfayı açan herkese açık hale getirir.