Meshy API Webhook'ları ve Yoklama: Sonuçlar Ne Zaman Hazır Olur

Meshy API üretim görevleri (Text to 3D, Image to 3D, Rigging ve daha fazlası) asenkron çalışır — bir görev gönderirsiniz ve ardından sonucu almadan önce görevin ne zaman tamamlandığını öğrenmeniz gerekir. Bu makale, görev yaşam döngüsünü ve bir görevin ne zaman tamamlandığını öğrenmenin desteklenen iki yolunu açıklar: yoklama ve webhook'lar — ayrıca en yaygın "model alınırken oluşan hatalar" sorunundan nasıl kaçınılacağını.

Her üretim görevi, görev nesnesinin status alanında döndürülen birkaç durumdan geçer:

• PENDING — görev sıraya alındı ancak işleme henüz başlamadı.

• IN_PROGRESS — görev aktif olarak işleniyor. progress alanı (0-100) iş tamamlandıkça artar.

• SUCCEEDED — görev başarıyla tamamlandı ve progress 100. Sonuç URL'leri (model dosyaları, dokular, önizlemeler) artık yanıtta mevcut.

• FAILED — görev tamamlanamadı. Başarısız görevler için krediler otomatik olarak iade edilir.

• CANCELED — görev tamamlanmadan önce iptal edildi.

API ile entegre ederken en önemli kural: Görevin status değeri SUCCEEDED olana kadar sonuç URL'lerini getirmeye veya kullanmaya asla çalışmayın. Bir görev hâlâ PENDING veya IN_PROGRESS durumindeyken sonuçları okumaya çalışmak, "model alınırken hatalar" raporlarının en yaygın nedenidir.

Yoklama, bir terminal durumuna ulaşana kadar (SUCCEEDED, FAILED veya CANCELED) görev kimliğiniz için "get task" uç noktasını tekrar tekrar çağırmak anlamına gelir. Basit bir yoklama döngüsü şu şekildedir:

• Üretim isteğini gönderin ve döndürülen görev id'sini saklayın.

• İlgili "retrieve task" uç noktasını (örneğin, Text to 3D veya Image to 3D task-by-id uç noktası) belirli aralıklarla çağırın — birkaç saniye tipiktir.

• Her yanıtta status alanını kontrol edin. Durum PENDING veya IN_PROGRESS olduğu sürece yoklamaya devam edin.

• status değeri SUCCEEDED (sonuç URL'lerini okuyun), FAILED veya CANCELED olur olmaz yoklamayı durdurun.

• Takılıp kalan bir görevin sonsuza kadar yoklama yapmaması için istemcinizde makul bir zaman aşımı/maksimum deneme koruması ekleyin.

Yoklama basittir ve komut dosyaları, toplu işler ve düşük hacimli entegrasyonlar için iyi çalışır. Yüksek hacimli veya gecikme süresine duyarlı entegrasyonlar için webhook genellikle daha uygun bir seçimdir.

Sürekli "tamamlandı mı?" diye sormak yerine, Meshy'den bir görev tamamlandığı anda sunucunuza bildirim göndermesini isteyebilirsiniz. Webhook'ları kullanmak için:

• Meshy'nin erişebileceği bir webhook (geri çağırma) URL'si yapılandırın — bu genellikle hesap/API ayarları düzeyinde belirlenir veya uç noktaya bağlı olarak üretim isteğinde parametre olarak iletilir.

• Uç noktanızın HTTPS üzerinden herkese açık şekilde erişilebilir olduğundan ve hızlı yanıt verdiğinden emin olun (hemen bir 2xx durumu döndürün, ardından yükü eşzamansız olarak işleyin).

• Görev terminal bir duruma ulaştığında Meshy, uç noktanıza görevin id değerini ve nihai status değerini içeren bir yük gönderir.

• Yükü aldığınızda, yalnızca webhook gövdesine güvenmek yerine id üzerinden API aracılığıyla görevin tam ayrıntılarını sorgulayın; böylece yetkili ve güncel sonuca sahip olduğunuzdan emin olun.

Webhook'lar gereksiz API çağrılarını azaltır ve neredeyse anlık bildirim sağlar; ancak webhook teslimatının atlanabileceği veya gecikebileceği görevler için (örneğin sizin tarafınızdaki geçici bir ağ sorunu nedeniyle) yine de periyodik bir yoklama yedeği bulundurmalısınız.

İster yoklama ister webhook'lar kullanın, sonuç işleme kodunuz idempotent olmalıdır — aynı görev için yan etki yaratmadan birden fazla kez çalıştırılması güvenli olmalıdır. Bu önemlidir çünkü:

• Aynı görev için bir webhook birden fazla kez teslim edilebilir (gönderen taraftaki yeniden denemeler, ağ çoğaltması vb.).

• Hem bir yoklama döngüsü hem de bir webhook işleyicisi çalışıyorsa, ikisi de aynı tamamlanmış görevi işlemeye çalışabilir.

Idempotent kalmak için işleme mantığınızı görev id değerine göre anahtarlayın — örneğin, yeniden yapmadan önce bu id için sonuçları zaten saklayıp indirmediğinizi kontrol edin ve "işlendi olarak işaretle" adımını kendi veritabanınızda tek bir atomik adım haline getirin.

"status": "SUCCEEDED" ve "progress": 100 içeren bir yanıt, sonuç yükünün (model URL'leri, dokular, küçük resimler) tamamlandığını ve kullanıma hazır olduğunu garanti eden tek sinyaldir. Somut olarak, kodunuzda:

• result/model URL alanlarından herhangi bir şey okumadan önce status === "SUCCEEDED" ifadesini doğrulayın.

• Yalnızca progress'e güvenmeyin — görev tamamen sonlandırılmadan önce progress kısa süreliğine yüksek değerler gösterebileceğinden, status'ı da her zaman kontrol edin.

• SUCCEEDED olduktan sonra sonuç dosyalarını hemen indirin — oluşturulan varlıklar yalnızca sınırlı bir süre boyunca Meshy'nin sunucularında saklanır, bu süre sonunda URL'ler artık çözümlenmeyecektir.

Çoğu "Modelimi alamıyorum" raporu bu nedenlerden birine dayanıyor:

• Çok erken getirme. status SUCCEEDED olmadan sonuç URL'sini çağırmak veya model alanlarını okumak. Bu, açık ara en yaygın nedendir.

• Süresi dolan varlıklar. SUCCEEDED olduktan sonra indirmek için çok uzun süre beklemek — sonuç URL'leri, o görev türü için saklama süresi geçtikten sonra çalışmayı durdurur.

• Eskimiş veya yanlış görev kimliği kullanmak — örneğin, önceki, ilgisiz bir istekten bir kimliği yeniden kullanmak.

• FAILED'ı geçici bir durummuş gibi ele almak ve yeniden göndermek yerine zaten başarısız olmuş bir görevi yoklamaya devam etmek.

• Sunucunuz ile Meshy arasındaki ağ/zaman aşımı sorunları — oluşturma sorunu olarak yanlış yorumlanabilir.

Bir oluşturma beklentilerinizi karşılamıyorsa veya bir istek tamamen başarısız olursa, aşağıdakileri göz önünde bulundurun:

• Meshy API şu anda mevcut bir görevi yerinde yeniden denemeyi desteklememektedir — tekrar denemek için yeni bir üretim isteği gönderin, bu normal şekilde kredi tüketir.

• API'yi çağırırken geçici ağ arızaları için (zaman aşımları, 5xx yanıtları), isteği yeniden göndermeden önce kısa bir üstel geri çekilme süresi makuldür.

• Yoklama için, geçici ağ hatalarında "görev al" çağrısını yeniden deneyin, ancak tek bir başarısız yoklamayı bir üretim hatası olarak değerlendirmeyin — yalnızca başarılı bir yanıt aldığınızda status alanına güvenin.

• Üretimler için yerleşik yeniden deneme işlevsiliğine ihtiyacınız varsa, kurumsal plan seçenekleri hakkında Meshy'nin satış ekibiyle iletişime geçin.

Bu durum neredeyse her zaman, kod görev bitmeden önce sonucu okumaya çalıştığı için gerçekleşir. Model URL'lerini almadan önce her zaman status'un SUCCEEDED (ve progress'un 100) olduğunu doğrulayın.

Yoklama, kurulumu daha basittir ve düşük hacimli veya tek seferlik betikler için idealdir. Webhook'lar, çok sayıda eşzamanlı görev içeren üretim entegrasyonları için daha iyidir; gereksiz tekrarlanan isteklerden kaçınır ve bir görev tamamlandığında sizi hemen bilgilendirir.

Idempotent şekilde işleyin — görev id'sini zaten işlediklerinize karşı kontrol edin ve zaten işlenmişse yeniden işlemeyi atlayın.

Görevi id ile doğrudan yoklayarak geri dönün. Ayrıca uç noktanızın HTTPS üzerinden herkese açık şekilde erişilebilir olduğunu ve hızlı bir 2xx yanıtı döndürdüğünü doğrulayın; yavaş veya erişilemeyen uç noktalar teslimat sorunlarına neden olabilir.

Şu anda değil — yeni bir üretim isteği göndermeniz gerekir ve bu normal şekilde kredi tüketir. Yerleşik yeniden deneme desteğine ihtiyacınız varsa kurumsal seçenekler hakkında satış ekibiyle iletişime geçin.

Sonuç dosyaları bir görev tamamlandıktan sonra Meshy'nin sunucularında yalnızca sınırlı bir süre saklanır; bu nedenle görev başarılı olduğunda çıktıları kendi depolama alanınıza hemen indirin, beklemeyin.