# Meshy API: Webhooki czy polling – kiedy wyniki są gotowe

> URL: https://help.meshy.ai/pl/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready
> Language: pl
> Last updated: 2026-09-09T10:36:30Z

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”.

## Cykl życia zadania

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”.

## Przykład pollingu

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.

## Konfiguracja webhooka

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).

## Idempotencja

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.

### status = SUCCEEDED

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ć.

## Częste błędy

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.

## Ponowne próby

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.

## FAQ

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

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.

### 2. Czy powinienem używać pollingu czy webhooków?

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.

### 3. Co powinien zrobić mój serwer, jeśli otrzyma ten sam webhook dwukrotnie?

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

### 4. Mój webhook nigdy nie dotarł — co powinienem zrobić?

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.

### 5. Czy mogę ponowić nieudane lub niezadowalające generowanie bezpośrednio przez API?

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.

### 6. Ile czasu mam na pobranie wyników po ustawieniu statusu SUCCEEDED?

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ć.

## Powiązane artykuły

- [Dlaczego konsekwentnie występują błędy podczas pobierania modeli z wyniku generowania przez API?](/pl/articles/9992036-why-do-i-consistently-encounter-errors-when-retrieving-the-models-from-generation-result-using-api)