Hatalar

Bir isteğin veya görevin neden başarısız olduğunu ve sırada ne yapmanız gerektiğini öğrenin. Bir istek hemen bir HTTP hatasıyla başarısız olabilir, bir görev ise daha sonra bir task_error ile başarısız olabilir.

İstek hataları

Meshy, bir isteği reddettiğinde bu hataları hemen döndürür. Neyin yanlış gittiğini öğrenmek için HTTP durum kodunu ve message alanını kontrol edin.

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

Görev hataları

Meshy'nin oluşturduğu bir görev, çalışırken yine de başarısız olabilir. status değeri FAILED olur, Meshy kredilerini iade eder ve task_error bunun nedenini açıklar.

{
  "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, hatanın genel kategorisidir. Bir sonraki adımda ne yapacağınıza karar vermek için bunu kullanın.

Hata kodları

code mevcut olduğunda, aşağıdaki sorunlardan birini adlandırır.

image_too_complex

Girdi görseli veya prompt, 3D üretim için geometrik olarak çok karmaşık olan bir konuyu tanımlıyor.

Örneğin:

• Meyve dolu bir kasa veya bir yığın kitap gibi küçük nesnelerin yoğun yığınları
• Kafes yapılar, iskeleler veya tel örgüler gibi karmaşık tekrarlayan desenler
• Çok sayıda pencere ve balkonu olan çok katlı binalar gibi karmaşık yapılar
• Tek bir konu yerine bir görselde birden fazla farklı nesne

Bu girdiler muhtemelen çok karmaşıktır:

Bunu düzeltmek için aşağıdakilerden birini veya birkaçını deneyin:

• Görsel başına tek bir nesne kullanın. Meshy, tek ve net bir konuyla en iyi şekilde çalışır, bu yüzden aynı görsel veya prompt içine birden fazla ayrı nesne koymayın.
• Konunuzu basitleştirin. Örneğin, onlarca çiçekle dolu bir vazo yerine basit bir vazo kullanın.
• Sahnelerden kaçının. Bütün binalar, şehir blokları, eşyalı odalar ve manzaralar muhtemelen fazla karmaşık olacaktır. Tek bir nesneye odaklanın.
• Yoğun tekrarlayan yapılardan kaçının. İskeleler, tel örgüler, kafesler ve küçük nesne yığınları yaygın tetikleyicilerdir.

model_missing_uv

Modeli dokulandırmak için enable_original_uv değeri true olarak ayarlanmış şekilde gönderdiniz, ancak modelde UV koordinatları yok. UV koordinatları, 2D bir dokunun 3D yüzeye nasıl sarılacağını tanımlar.

Bunu düzeltmek için aşağıdakilerden birini yapın:

• Modelinizin kendi UV yerleşimini korumak istiyorsanız, örneğin özel dikiş (seam) yerleşimi için, 3D yazılımınızda modele UV ekleyin. Yazılımın UV düzenleyicisinde bunları kontrol edin, ardından modeli tekrar yükleyin. STL dosyaları UV'leri saklayamaz, bu yüzden GLB, FBX veya OBJ kullanın.
• Kendi yerleşiminize ihtiyacınız yoksa veya emin değilseniz, enable_original_uv parametresini belirtmeyin ya da false olarak ayarlayın. Meshy daha sonra model için bir UV yerleşimi oluşturur. Yeni UV'ler modeli iyi şekilde kaplar, ancak doku dikişlerinin nereye gideceğini kontrol edemezsiniz.

model_insufficient_uv

Modelin UV koordinatları var, ancak bunlar UV uzayının çok küçük bir kısmını kapladığından iyi bir dokulama sağlayamıyor. Bu durum genellikle dışa aktarıcısının düzgün bir unwrap işlemi yapmadan yer tutucu veya çökmüş UV'ler yazdığı modellerde ortaya çıkar.

Bunu düzeltmek için aşağıdakilerden birini yapın:

• Kendi UV yerleşiminizi korumak istiyorsanız, modelin UV'lerini 3D yazılımınızda yeniden unwrap edin. Ada parçalarını (island) UV uzayının küçük bir köşesine sıkıştırmak yerine tüm alana yayın.
• Kendi yerleşiminize ihtiyacınız yoksa, enable_original_uv değerini belirtmeyin veya false olarak ayarlayın. Bu durumda Meshy yeni bir UV yerleşimi oluşturur. Dikiş yerleşiminizi kaybedersiniz, ancak yeni UV'ler dokulama için yeterli alanı kaplar.

model_missing_texture

Bir Multi-Color Print görevinin giriş modelinde, Meshy'nin baskı renklerine ayırabileceği hiçbir renk bulunmuyor. Meshy, çok renkli bir 3MF'yi modelin renklerinden oluşturur, bu yüzden düz beyaz bir ağ üzerinde çalışacak hiçbir şey yoktur. Örneğin, hiç dokulandırılmamış bir Metinden 3D'ye veya Görselden 3D'ye önizlemesinde renk bulunmaz. Aynı şekilde Basılabilirliği onar işleminin çıktısında veya dokuyu korumayan bir Auto Split görevinde de renk bulunmaz.

Neyin renk sayıldığı, talep ettiğiniz style değerine bağlıdır:

• realistic, temel renk dokusunu modelin UV'leri üzerinden örnekler. Tek bir temel renk dokusuna ve her ağ parçasında UV'lere ihtiyaç duyar.
• cartoon, renkleri yüz başına düzleştirir. Herhangi bir parça üzerindeki temel renk dokusunu veya köşe başına renkleri (COLOR_0) kabul eder.

Meshy, her iki stil için de ne temel renk dokusu ne de köşe renkleri bulunan bir modeli reddeder; bunun yerine cartoon'un modeli tek renkli bir baskıya dönüştürmesine izin vermez.

Meshy, bu isteklerin çoğunu görevi oluşturmadan önce, aynı açıklamayla birlikte bir 400 döndürerek reddeder. Bu kodu genellikle yalnızca Meshy'nin girdiyi önceden kontrol edemediği durumlarda alırsınız. Örneğin, Meshy bir .fbx yüklemesini yalnızca görev onu dönüştürdükten sonra kontrol eder.

Bunu düzeltmek için modelinize uygun seçeneği kullanın:

• Önce modeli dokulandırın. Bunun üzerinde Yeniden dokulama çalıştırın, ya da bir Metinden 3D'ye refine görevi veya should_texture: true ile bir Görselden 3D'ye görevi kullanarak oluşturun. Ardından bu görevi input_task_id olarak gönderin.
• Bir fotogrametri taraması veya elle boyanmış bir ağ gibi köşe renkli bir model için, COLOR_0'ı okuyan style: "cartoon" kullanın.
• realistic ile kısmen dokulanmış veya çok dokulu bir model için, her ağ parçasına UV'ler ve aynı tek temel renk dokusunu verin. Bunu yapmak için kalan parçaları dokulandırın veya dokuları tek bir atlasta birleştirin. Ayrıca style: "cartoon"'a da geçebilirsiniz.

textured_split_refused

keep_texture: true ayarına sahip bir Auto Split görevi, girdi modelin dokusunu parçalar üzerinde koruyamaz. Örneğin, modelde UV yoktur veya dokusunda, kesimlerin oluşturduğu yeni yüzeyler için yer yoktur. Meshy, kredileri iade eder.

Bunu düzeltmek için isteği keep_texture olmadan veya keep_texture: false ile tekrar gönderin. Parçalar bu durumda her biri düz bir renkle geri döner.

invalid_input

Girdi bir kontrolden geçemedi ve bundan daha spesifik bir kod geçerli değil. message, nedeni belirtir.

Örneğin:

• Boş veya bozuk bir model dosyası
• Bir dosya biçiminin desteklenmeyen bir varyantı, örneğin bir ASCII FBX dosyası veya meshopt ile sıkıştırılmış bir GLB dosyası
• Geçerli 3D nesnesi olmayan yüklenmiş bir model, örneğin yalnızca iskeletler (armature), kameralar veya ışıklar içeren bir dosya
• Güvenlik filtrelerinden geçemeyen içerik

Bunu düzeltmek için, belirli sorunu öğrenmek üzere message değerini okuyun. Girdi dosyalarınızın ve parametrelerinizin uç noktanın gereksinimlerini karşıladığından emin olun.

moderation_blocked

Güvenlik filtreleri, prompt'unuzu veya referans görsellerinizi reddetti. Filtreler metni ve görselleri birlikte kontrol eder.

Bunu düzeltmek için aşağıdakilerden birini veya her ikisini yapın:

• Müstehcen veya hassas tanımları kaldırmak için prompt'u yeniden ifade edin.
• Filtrelerin engelleyebileceği içerikleri gösteren referans görselleri değiştirin.

moderation_unavailable

Tür: server_error. İçerik moderation işlemi geçici olarak kullanılamadığından, Meshy kontrolü atlamak yerine görevi başarısız saydı. İçeriğinizle ilgili herhangi bir sorun yok.

Bunu düzeltmek için görevi yeniden oluşturun.

timeout

Görev, işleme veya kuyrukta bekleme için sunucu taraflı süre sınırını aştı, bu yüzden Meshy görevi başarısız sayıp kredilerini iade etti. Yüksek yük veya zamanında bitirilemeyecek kadar karmaşık bir girdi buna neden olabilir.

Bu, kendi kodunuzdaki bir timeout'tan farklıdır. İstemciniz beklemeyi durdursa bile görev hâlâ çalışıyor olabilir. Bkz. Ne kadar beklenmeli.

Bunu düzeltmek için şu adımları izleyin:

1. Görevi tekrar oluşturun. Timeout'lar genellikle geçicidir ve yeni bir görev başarılı olabilir.
2. Sorun devam ederse, görüntünüzdeki veya promptunuzdaki ayrıntıyı azaltmak gibi yollarla girdinizi basitleştirin. İşlenmesi daha zor girdiler için bkz. image_too_complex.

queue_timeout

Tür: timeout. Görev başlamadan kuyrukta çok uzun süre bekledi, bu nedenle Meshy görevi başarısız olarak işaretledi ve bunun için tahsil edilen tüm kredileri iade etti. Bu hataya sizin girdiğiniz veri neden olmadı.

Bunu düzeltmek için görevi yeniden oluşturun.

format_conversion_failed

Meshy modeli oluşturdu, ancak istediğiniz formata dönüştürme işlemi başarısız oldu.

Bunu düzeltmek için şu adımları izleyin:

1. Görevi yeniden oluşturun.
2. Bir format sürekli başarısız oluyorsa, ihtiyaçlarınıza uygun farklı bir format isteyin.

En iyi uygulamalar

• Başarısız görevleri yeniden deneyin. timeout, service_unavailable veya server_error ile başarısız olan bir görev için, üstel geri çekilme (exponential backoff) ile yeni bir görev oluşturun.
• Kendi isteğiniz zaman aşımına uğradığında yeni bir görev oluşturmayın. İlk görev hâlâ çalışıyor olabilir, bu yüzden başka bir görev oluşturmadan önce var olup olmadığını kontrol edin. Bkz. Ne kadar beklenmeli.
• Görev kimliklerini kaydedin. Destek ekibiyle iletişime geçtiğinizde kimliği belirtin.
• Girdileri göndermeden önce kontrol edin. Görsellerin ve modellerin uç noktanın biçim gereksinimlerini karşıladığından emin olun.
• API'yi sunucunuzdan çağırın. Tarayıcıda çalışan kod, API anahtarınızı sayfayı açan herkese ifşa eder.