Meshy API: webhooki kontra odpytywanie — kiedy wyniki są gotowe

Zadania generowania w Meshy API (Text to 3D, Image to 3D, Rigging i inne) działają asynchronicznie — wysyłasz zadanie, a następnie musisz ustalić, kiedy zostało ukończone, zanim pobierzesz wynik. W tym artykule wyjaśniamy cykl życia zadania oraz dwa obsługiwane sposoby sprawdzania, czy zadanie zostało ukończone: odpytywanie i webhooki — a także jak uniknąć najczęstszego problemu z „błędami podczas pobierania modelu”.

Każde zadanie generowania przechodzi przez niewielki zestaw stanów, zwracanych w polu status obiektu zadania:

• PENDING — zadanie zostało zakolejkowane, ale przetwarzanie jeszcze się nie rozpoczęło.

• IN_PROGRESS — zadanie jest aktywnie przetwarzane. Pole progress (0-100) rośnie w miarę postępu prac.

• SUCCEEDED — zadanie zakończyło się pomyślnie, a progress wynosi 100. Adresy URL wyników (pliki modeli, tekstury, podglądy) są teraz dostępne w odpowiedzi.

• FAILED — zadania nie udało się ukończyć. Kredyty za nieudane zadania są automatycznie zwracane.

• CANCELED — zadanie zostało anulowane przed ukończeniem.

Najważniejsza zasada integracji z API: nigdy nie próbuj pobierać ani używać adresów URL wyników, dopóki status zadania nie ma wartości SUCCEEDED. Odczytywanie wyników, gdy zadanie ma jeszcze status PENDING lub IN_PROGRESS, to najczęstsza przyczyna zgłoszeń o „błędach podczas pobierania modelu”.

Odpytywanie polega na wielokrotnym wywoływaniu punktu końcowego „pobierz zadanie” dla swojego identyfikatora zadania, aż osiągnie ono stan końcowy (SUCCEEDED, FAILED lub CANCELED). Prosta pętla odpytywania wygląda tak:

• Wyślij żądanie generowania i zapisz zwrócony identyfikator zadania id.

• Wywołuj odpowiedni punkt końcowy „pobierz zadanie” (na przykład punkt końcowy zadania Text to 3D lub Image to 3D według identyfikatora) w regularnych odstępach — typowo co kilka sekund.

• Sprawdzaj pole status w każdej odpowiedzi. Odpytuj dalej, gdy ma wartość PENDING lub IN_PROGRESS.

• Zakończ odpytywanie, gdy tylko status przyjmie wartość SUCCEEDED (odczytaj adresy URL wyników), FAILED lub CANCELED.

• Dodaj w swoim kliencie rozsądny limit czasu i maksymalną liczbę prób, aby zablokowane zadanie nie było odpytywane w nieskończoność.

Odpytywanie jest proste i dobrze sprawdza się w skryptach, zadaniach wsadowych oraz integracjach o małym natężeniu ruchu. W integracjach o dużym natężeniu ruchu lub wrażliwych na opóźnienia zwykle lepiej sprawdza się webhook.

Zamiast wielokrotnie pytać „czy to już gotowe?”, możesz poprosić Meshy o powiadomienie Twojego serwera w momencie zakończenia zadania. Aby korzystać z webhooków:

• Skonfiguruj adres URL webhooka (callback), który Meshy może osiągnąć — jest on zwykle ustawiany na poziomie ustawień konta/API lub przekazywany jako parametr w żądaniu generowania, w zależności od endpointu.

• Upewnij się, że Twój endpoint jest publicznie dostępny przez HTTPS i odpowiada szybko (natychmiast zwróć status 2xx, a następnie przetwórz payload asynchronicznie).

• Gdy zadanie osiągnie stan końcowy, Meshy wysyła payload na Twój endpoint zawierający id zadania i jego końcowy status.

• Po otrzymaniu powiadomienia pobierz pełne szczegóły zadania po id przez API, zamiast polegać wyłącznie na treści webhooka, aby mieć pewność, że dysponujesz wiążącym, aktualnym wynikiem.

Webhooki ograniczają zbędne wywołania API i zapewniają niemal natychmiastowe powiadomienie, ale nadal warto utrzymywać okresowe odpytywanie jako mechanizm zapasowy dla zadań, w których dostarczenie webhooka może zostać pominięte lub opóźnione (np. z powodu przejściowego problemu sieciowego po Twojej stronie).

Niezależnie od tego, czy używasz odpytywania, czy webhooków, kod obsługujący wyniki powinien być idempotentny — czyli bezpieczny do wielokrotnego uruchomienia dla tego samego zadania bez skutków ubocznych. Ma to znaczenie, ponieważ:

• Ten sam webhook może zostać dostarczony więcej niż raz dla tego samego zadania (ponowne próby po stronie nadawcy, duplikacja w sieci itp.).

• Pętla odpytywania i obsługa webhooka mogą jednocześnie próbować przetworzyć to samo ukończone zadanie, jeśli obie działają.

Aby zachować idempotencję, opieraj logikę przetwarzania na id zadania — na przykład sprawdź, czy wyniki dla tego id zostały już zapisane/pobrane, zanim zrobisz to ponownie, i uczyń „oznaczenie jako przetworzone” pojedynczym niepodzielnym krokiem w swojej bazie danych.

Odpowiedź z "status": "SUCCEEDED" i "progress": 100 to jedyny sygnał gwarantujący, że ładunek wyniku (adresy URL modeli, tekstury, miniatury) jest kompletny i bezpieczny w użyciu. W praktyce w Twoim kodzie:

• Sprawdź status === "SUCCEEDED", zanim odczytasz cokolwiek z pól result/adresów URL modeli.

• Nie polegaj wyłącznie na progress — zawsze sprawdzaj także status, ponieważ postęp może chwilowo pokazywać wysokie wartości, zanim zadanie zostanie w pełni sfinalizowane.

• Pobierz pliki wynikowe niezwłocznie po osiągnięciu SUCCEEDED — wygenerowane zasoby są przechowywane na serwerach Meshy tylko przez ograniczony czas, po którym adresy URL przestaną działać.

Większość zgłoszeń „nie mogę pobrać swojego modelu” wynika z jednej z poniższych przyczyn:

• Zbyt wczesne pobieranie. Wywołanie adresu URL wyniku lub odczyt pól modelu, zanim status ma wartość SUCCEEDED. To zdecydowanie najczęstsza przyczyna.

• Wygasłe zasoby. Zbyt długie oczekiwanie po SUCCEEDED przed pobraniem — adresy URL wyników przestają działać po upływie okresu przechowywania dla danego typu zadania.

• Użycie nieaktualnego lub błędnego identyfikatora zadania — na przykład ponowne użycie identyfikatora z poprzedniego, niepowiązanego żądania.

• Traktowanie FAILED jako stanu przejściowego i dalsze odpytywanie zadania, które już się nie powiodło, zamiast ponownego przesłania.

• Problemy z siecią lub przekroczeniem limitu czasu między Twoim serwerem a Meshy, które są błędnie odczytywane jako problem z generowaniem.

Jeśli wygenerowany wynik nie spełnia Twoich oczekiwań lub żądanie kończy się niepowodzeniem, pamiętaj o następujących kwestiach:

• Meshy API nie obsługuje obecnie ponawiania istniejącego zadania w miejscu — aby spróbować ponownie, wyślij nowe żądanie generowania, które normalnie zużyje kredyty.

• W przypadku przejściowych awarii sieci podczas wywoływania API (przekroczenia limitu czasu, odpowiedzi 5xx) rozsądne jest krótkie wykładnicze opóźnienie przed ponownym wysłaniem żądania.

• W samym odpytywaniu ponów wywołanie „get task” w przypadku przejściowych błędów sieci, ale nie traktuj pojedynczego nieudanego odpytania jako niepowodzenia generowania — ufaj polu status dopiero po otrzymaniu pomyślnej odpowiedzi.

• Jeśli potrzebujesz wbudowanej funkcji ponawiania generowania, skontaktuj się z zespołem sprzedaży Meshy w sprawie opcji planu enterprise.

Dzieje się tak niemal zawsze dlatego, że kod próbuje odczytać wynik, zanim zadanie zostało ukończone. Zawsze potwierdź, że status ma wartość SUCCEEDED (a progress wynosi 100), zanim pobierzesz adresy URL modeli.

Odpytywanie jest prostsze w konfiguracji i sprawdza się w przypadku małego wolumenu lub jednorazowych skryptów. Webhooki lepiej nadają się do integracji produkcyjnych z wieloma równoczesnymi zadaniami, ponieważ pozwalają uniknąć niepotrzebnych powtarzanych żądań i natychmiast powiadamiają o ukończeniu zadania.

Obsłuż go idempotentnie — porównaj id zadania z tym, co już przetworzyłeś, i pomiń ponowne przetwarzanie, jeśli zostało już obsłużone.

Wróć do odpytywania zadania bezpośrednio po id. Upewnij się też, że Twój punkt końcowy jest publicznie dostępny przez HTTPS i zwraca szybką odpowiedź 2xx, ponieważ wolne lub niedostępne punkty końcowe mogą powodować problemy z dostarczaniem.

Obecnie nie — musisz przesłać nowe żądanie generowania, co normalnie zużywa kredyty. Skontaktuj się z działem sprzedaży w sprawie opcji enterprise, jeśli potrzebujesz wbudowanego wsparcia dla ponownych prób.

Pliki wynikowe są przechowywane na serwerach Meshy tylko przez ograniczony czas po ukończeniu zadania, więc pobierz wyniki do własnego magazynu, gdy tylko zadanie zakończy się sukcesem, zamiast czekać.