Meshy API Webhook ve Polling Karşılaştırması: Sonuçlar Ne Zaman Hazır Olur

Meshy API üretim görevleri (Text to 3D, Image to 3D, Rigging ve daha fazlası) asenkron olarak çalışır — bir görev gönderirsiniz ve sonucu almaya çalışmadan ö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 bittiğini öğrenmenin iki desteklenen yolunu açıklar: polling ve webhook — ayrıca en yaygın "model alınırken hata oluştu" sorunundan nasıl kaçınılacağını da açıklar.

Her üretim görevi, küçük bir durum kümesinden geçer ve görev nesnesinin status alanında döndürülür:

• 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'dür. Sonuç URL'leri (model dosyaları, dokular, önizlemeler) artık yanıtta mevcuttur.

• FAILED — görev tamamlanamadı. Başarısız görevlerin kredileri otomatik olarak iade edilir.

• CANCELED — görev tamamlanmadan iptal edildi.

API ile entegrasyon yaparken en önemli kural: görevin status değeri SUCCEEDED olana kadar asla sonuç URL'lerini getirmeyi veya kullanmayı denemeyin. Görev hâlâ PENDING veya IN_PROGRESS durumundayken sonuçları okumak, "model alınırken hata oluştu" bildirimlerinin en yaygın nedenidir.

Polling, görev kimliğiniz için "görevi getir" (get task) uç noktasını, bir son duruma (SUCCEEDED, FAILED veya CANCELED) ulaşana kadar tekrar tekrar çağırmak anlamına gelir. Basit bir polling döngüsü şöyle görünür:

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

• İlgili "görevi al" (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 tipik bir aralıktır.

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

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

• Takılı kalmış bir görevin sonsuza kadar polling yapmaması için istemcinize makul bir zaman aşımı/maksimum deneme sayısı sınırı ekleyin.

Polling basittir ve betikler, toplu işler ve düşük hacimli entegrasyonlar için iyi çalışır. Yüksek hacimli veya gecikmeye duyarlı entegrasyonlar için webhook genellikle daha uygundur.

"Bitti mi?" diye tekrar tekrar sormak yerine, Meshy'den bir görev bittiği anda sunucunuzu bilgilendirmesini 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 ayarlanır veya uç noktaya bağlı olarak üretim isteğinde bir parametre olarak iletilir.

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

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

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

Webhook'lar gereksiz API çağrılarını azaltır ve neredeyse anında bildirim sağlar, ancak webhook teslimatının kaçırılabileceği veya gecikebileceği görevler için (örneğin sizin tarafınızda geçici bir ağ sorunu nedeniyle) yine de periyodik bir polling yedeği bulundurmalısınız.

Polling veya webhook kullanıp kullanmadığınıza bakılmaksızın, sonuç işleme kodunuz idempotent olmalıdır — yani aynı görev için yan etkiler oluşturmadan birden fazla kez çalıştırılması güvenli olmalıdır. Bu şu nedenlerle önemlidir:

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

• Bir polling döngüsü ve bir webhook işleyicisi, her ikisi de çalışıyorsa aynı tamamlanmış görevi işlemeye çalışabilir.

Idempotent kalmak için işleme mantığınızı görev id değerine dayandırın — örneğin, tekrar yapmadan önce o id için sonuçları zaten saklayıp indirmediğinizi kontrol edin ve "işlenmiş 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) eksiksiz olduğunu ve güvenle kullanılabileceğini garanti eden tek sinyaldir. Somut olarak, kodunuzda:

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

• Yalnızca progress değerine güvenmeyin — her zaman status değerini de kontrol edin, çünkü görev tam olarak sonlandırılmadan önce progress kısa süreliğine yüksek değerler gösterebilir.

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

"Modelimi alamıyorum" bildirimlerinin çoğu şu nedenlerden birine dayanır:

• Çok erken getirmek. status değeri SUCCEEDED olmadan sonuç URL'sini çağırmak veya model alanlarını okumak. Bu, açık ara en sık görülen nedendir.

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

• Eski veya yanlış bir görev kimliği kullanmak — örneğin, önceki, alakasız bir istekten gelen bir kimliği yeniden kullanmak.

• FAILED durumunu geçici bir durum olarak ele almak ve yeniden göndermek yerine, zaten başarısız olmuş bir görevi polling yapmaya devam etmek.

• Sunucunuz ile Meshy arasındaki ağ/zaman aşımı sorunlarının bir üretim sorunu olarak yanlış yorumlanması.

Bir üretim beklentilerinizi karşılamıyorsa veya bir istek tamamen başarısız oluyorsa, şunları aklınızda bulundurun:

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

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

• Polling'in kendisi için, geçici ağ hatalarında "görevi getir" çağrısını yeniden deneyin, ancak tek bir başarısız polling'i bir üretim hatası olarak ele almayın — başarılı bir yanıt aldığınızda yalnızca status alanına güvenin.

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

Bu neredeyse her zaman, kodun görev bitmeden sonucu okumaya çalışmasından kaynaklanır. Model URL'lerini almadan önce her zaman status değerinin SUCCEEDED olduğunu (ve progress değerinin 100 olduğunu) doğrulayın.

Polling kurulumu daha basittir ve düşük hacimli veya tek seferlik betikler için uygundur. Webhook'lar, çok sayıda eşzamanlı görevi olan üretim entegrasyonları için daha iyidir; çünkü gereksiz tekrarlanan isteklerden kaçınırlar ve bir görev tamamlandığında sizi anında bilgilendirirler.

Idempotent şekilde işleyin — görev id değerini halihazırda işlediklerinizle karşılaştırın ve zaten işlenmişse yeniden işlemeyi atlayın.

Doğrudan id ile görevi polling yaparak yedeğe geçin. 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; çünkü yavaş veya erişilemez uç noktalar teslimat sorunlarına neden olabilir.

Şu anda hayır — normal şekilde kredi harcayacak yeni bir üretim isteği göndermeniz gerekir. 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 yalnızca sınırlı bir süre boyunca Meshy'nin sunucularında saklanır; bu nedenle beklemek yerine görev başarar başarmaz çıktıları kendi depolama alanınıza indirin.

• API Kullanarak Üretim Sonucundan Modelleri Alırken Neden Sürekli Hatalarla Karşılaşıyorum?