Meshy API: Webhooki czy polling – 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 dowiedzieć się, kiedy jest gotowe, zanim pobierzesz wynik. W tym artykule opisujemy cykl życia zadania oraz dwa obsługiwane sposoby sprawdzenia, kiedy zadanie zostało ukończone: polling i webhooki — a także jak uniknąć najczęstszego problemu „błędy podczas pobierania modelu”.

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

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

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

• 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 — zadanie nie mogło zostać ukończone. Kredyty za nieudane zadania są automatycznie zwracane.

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

Najważniejsza zasada podczas 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 jest wciąż w stanie PENDING lub IN_PROGRESS, to najczęstsza przyczyna zgłoszeń „błędy podczas pobierania modelu”.

Polling oznacza wielokrotne wywoływanie endpointu „pobierz zadanie” dla identyfikatora Twojego zadania, aż osiągnie ono stan końcowy (SUCCEEDED, FAILED lub CANCELED). Prosta pętla pollingu wygląda tak:

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

• Wywołuj odpowiedni endpoint „pobierz zadanie” (na przykład endpoint zadania Text to 3D lub Image to 3D według identyfikatora) w odstępach czasu — zwykle co kilka sekund.

• Sprawdzaj pole status w każdej odpowiedzi. Kontynuuj polling, dopóki ma wartość PENDING lub IN_PROGRESS.

• Zatrzymaj polling, gdy tylko status przyjmie wartość SUCCEEDED (odczytaj adresy URL wyników), FAILED lub CANCELED.

• Dodaj w swoim kliencie rozsądny limit czasu/maksymalną liczbę prób, aby zadanie utknięte nie pollowało w nieskończoność.

Polling jest prosty i dobrze sprawdza się w skryptach, zadaniach wsadowych i integracjach o małej skali. W przypadku integracji o dużej skali lub wrażliwych na opóźnienia lepszym rozwiązaniem jest zwykle webhook.

Zamiast wciąż pytać „czy już gotowe?”, możesz poprosić Meshy, aby powiadomił Twój serwer w momencie zakończenia zadania. Aby korzystać z webhooków:

• Skonfiguruj adres URL webhooka (callback), do którego Meshy może się dostać — zwykle ustawia się go na poziomie ustawień konta/API lub przekazuje jako parametr żądania 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 ładunek przetwarzaj asynchronicznie).

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

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

Webhooki ograniczają zbędne wywołania API i zapewniają niemal natychmiastowe powiadomienie, ale mimo to warto zachować okresowy polling jako rozwiązanie zapasowe dla zadań, w których dostarczenie webhooka może zostać pominięte lub opóźnione (np. z powodu chwilowego problemu sieciowego po Twojej stronie).

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

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

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

Aby zachować idempotencję, opieraj logikę przetwarzania na id zadania — na przykład sprawdź, czy wyniki dla danego id zostały już zapisane/pobrane, zanim zrobisz to ponownie, i uczynij „oznaczenie jako przetworzone” pojedynczym atomowym krokiem we własnej 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. Konkretnie, w Twoim kodzie:

• Zweryfikuj status === "SUCCEEDED", zanim odczytasz cokolwiek z pól result/adresu URL modelu.

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

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

Większość zgłoszeń „nie mogę pobrać mojego modelu” sprowadza się do jednej z następujących przyczyn:

• Pobieranie zbyt wcześnie. Wywołanie adresu URL wyniku lub odczyt pól modelu, zanim status przyjmie wartość SUCCEEDED. To zdecydowanie najczęstsza przyczyna.

• Wygaśnięcie zasobów. Zbyt długie oczekiwanie po SUCCEEDED z 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 ID z poprzedniego, niezwiązanego żądania.

• Traktowanie FAILED jako stanu przejściowego i dalszy polling zadania, które już się nie powiodło, zamiast ponownego wysłania żądania.

• Problemy sieciowe/limity czasu między Twoim serwerem a Meshy, błędnie odczytywane jako problem z generowaniem.

Jeśli wynik generowania nie spełnia Twoich oczekiwań lub żądanie całkowicie się nie powiedzie, weź pod uwagę następujące kwestie:

• 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 błędów sieciowych podczas wywoływania API (limity czasu, odpowiedzi 5xx) rozsądne jest krótkie wycofywanie wykładnicze przed ponownym wysłaniem żądania.

• Przy samym pollingu ponawiaj wywołanie „pobierz zadanie” przy przejściowych błędach sieciowych, ale nie traktuj pojedynczego nieudanego odpytania jako niepowodzenia generowania — ufaj polu status dopiero po otrzymaniu poprawnej odpowiedzi.

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

Zwykle dzieje się tak, ponieważ kod próbuje odczytać wynik, zanim zadanie zostało ukończone. Zawsze upewnij się, że status ma wartość SUCCEEDED (a progress wynosi 100), zanim pobierzesz adresy URL modelu.

Polling jest prostszy w konfiguracji i sprawdzi się przy małej liczbie żądań czy w skryptach jednorazowych. Webhooki są lepsze dla integracji produkcyjnych z wieloma równoległymi zadaniami, ponieważ eliminują zbędne powtarzane żądania i natychmiast powiadamiają o zakończeniu zadania.

Obsłuż go idempotentnie — sprawdź id zadania względem już przetworzonych i pomiń ponowne przetwarzanie, jeśli zostało już obsłużone.

Wróć do pollingu zadania bezpośrednio według id. Sprawdź też, czy Twój endpoint jest publicznie dostępny przez HTTPS i szybko zwraca odpowiedź 2xx, ponieważ wolne lub niedostępne endpointy mogą powodować problemy z dostarczaniem.

Obecnie nie — musisz wysłać nowe żądanie generowania, które normalnie zużyje kredyty. Skontaktuj się z działem sprzedaży w sprawie opcji enterprise, jeśli potrzebujesz wbudowanej obsługi ponawiania.

Pliki wyników są przechowywane na serwerach Meshy tylko przez ograniczony czas po zakończeniu zadania, dlatego pobierz wyniki do własnego magazynu jak najszybciej po pomyślnym zakończeniu zadania, zamiast czekać.

• Dlaczego konsekwentnie występują błędy podczas pobierania modeli z wyniku generowania przez API?