Meshy API Webhooks vs Polling: Wanneer resultaten klaar zijn

Generatietaken van de Meshy API (Text to 3D, Image to 3D, Rigging en meer) worden asynchroon uitgevoerd — je dient een taak in en moet vervolgens achterhalen wanneer deze klaar is voordat je het resultaat ophaalt. Dit artikel legt de taaklevenscyclus uit en de twee ondersteunde manieren om te weten wanneer een taak is voltooid: polling en webhooks — plus hoe je het meest voorkomende probleem "fouten bij het ophalen van het model" voorkomt.

Elke generatietaak doorloopt een klein aantal statussen, die worden teruggegeven in het veld status van het taakobject:

• PENDING — de taak is in de wachtrij geplaatst, maar de verwerking is nog niet begonnen.

• IN_PROGRESS — de taak wordt actief verwerkt. Het veld progress (0-100) loopt op naarmate het werk vordert.

• SUCCEEDED — de taak is succesvol afgerond en progress is 100. Resultaat-URL's (modelbestanden, textures, previews) zijn nu beschikbaar in de respons.

• FAILED — de taak kon niet worden voltooid. Credits voor mislukte taken worden automatisch terugbetaald.

• CANCELED — de taak is geannuleerd voordat deze was voltooid.

De allerbelangrijkste regel bij integratie met de API: probeer nooit resultaat-URL's op te halen of te gebruiken voordat de status van de taak SUCCEEDED is. Resultaten lezen terwijl een taak nog PENDING of IN_PROGRESS is, is de meest voorkomende oorzaak van meldingen over "fouten bij het ophalen van het model".

Polling betekent dat je herhaaldelijk het "get task"-endpoint aanroept voor je taak-ID totdat de taak een terminale status bereikt (SUCCEEDED, FAILED of CANCELED). Een eenvoudige polling-lus ziet er als volgt uit:

• Dien het generatieverzoek in en sla de geretourneerde taak-id op.

• Roep het bijbehorende "retrieve task"-endpoint (bijvoorbeeld het Text to 3D- of Image to 3D-taak-op-ID-endpoint) met een interval aan — een paar seconden is gebruikelijk.

• Controleer het veld status in elke respons. Blijf pollen zolang deze PENDING of IN_PROGRESS is.

• Stop met pollen zodra status SUCCEEDED is (lees de resultaat-URL's), FAILED of CANCELED.

• Voeg een redelijke timeout of limiet op het maximumaantal pogingen toe in je client, zodat een vastgelopen taak niet voor altijd blijft pollen.

Polling is eenvoudig en werkt goed voor scripts, batchtaken en integraties met een laag volume. Voor integraties met een hoog volume of die latentiegevoelig zijn, is een webhook meestal geschikter.

In plaats van herhaaldelijk te vragen "is het al klaar?", kun je Meshy vragen om je server te waarschuwen zodra een taak is voltooid. Om webhooks te gebruiken:

• Configureer een webhook (callback) URL die Meshy kan bereiken — dit wordt meestal ingesteld op account/API-instellingsniveau of doorgegeven als parameter bij de generatie-aanvraag, afhankelijk van het eindpunt.

• Zorg ervoor dat je eindpunt openbaar bereikbaar is via HTTPS en snel reageert (stuur onmiddellijk een 2xx-status, verwerk de payload daarna asynchroon).

• Wanneer de taak een terminale status bereikt, stuurt Meshy een payload naar je eindpunt met de taak-id en de uiteindelijke status.

• Bij ontvangst kun je de volledige taakdetails opzoeken via id via de API in plaats van alleen op de webhook-body te vertrouwen, om zo het gezaghebbende, actuele resultaat te verkrijgen.

Webhooks verminderen onnodige API-aanroepen en geven je vrijwel onmiddellijke notificatie, maar je moet nog steeds een periodieke polling-terugval houden voor taken waarbij webhook-bezorging gemist of vertraagd kan zijn (bijv. door een tijdelijk netwerkprobleem aan jouw zijde).

Of je nu polling of webhooks gebruikt, je code voor het verwerken van resultaten moet idempotent zijn — veilig om meer dan eens uit te voeren voor dezelfde taak zonder bijwerkingen. Dit is belangrijk omdat:

• Een webhook mogelijk meer dan eens wordt afgeleverd voor dezelfde taak (nieuwe pogingen aan de kant van de afzender, netwerkduplicatie, enz.).

• Een polling-lus en een webhook-handler kunnen allebei proberen dezelfde voltooide taak te verwerken als beide actief zijn.

Om idempotent te blijven, baseer je je verwerkingslogica op de id van de taak — controleer bijvoorbeeld of je al resultaten voor die id hebt opgeslagen/gedownload voordat je dit opnieuw doet, en maak "markeren als verwerkt" één atomaire stap in je eigen database.

Een antwoord met "status": "SUCCEEDED" en "progress": 100 is het enige signaal dat garandeert dat de resultaatpayload (model-URL's, textures, thumbnails) compleet en veilig te gebruiken is. Concreet, in je code:

• Controleer status === "SUCCEEDED" voordat je iets uit de result/model-URL-velden leest.

• Vertrouw niet alleen op progress — controleer altijd ook status, omdat progress kortstondig hoge waarden kan tonen voordat de taak volledig is afgerond.

• Download resultaatbestanden snel zodra SUCCEEDED is bereikt — gegenereerde assets worden slechts beperkte tijd op Meshy's servers bewaard, waarna de URL's niet meer werken.

De meeste meldingen van het type "ik kan mijn model niet ophalen" zijn terug te voeren op een van deze oorzaken:

• Te vroeg ophalen. De resultaat-URL aanroepen of de modelvelden uitlezen voordat status gelijk is aan SUCCEEDED. Dit is veruit de meest voorkomende oorzaak.

• Verlopen assets. Te lang wachten met downloaden na SUCCEEDED — resultaat-URL's werken niet meer nadat het retentievenster voor dat taaktype is verstreken.

• Een verouderd of verkeerd taak-ID gebruiken — bijvoorbeeld een ID hergebruiken van een eerdere, niet-gerelateerde aanvraag.

• FAILED als een tijdelijke status behandelen en blijven pollen bij een taak die al is mislukt, in plaats van opnieuw in te dienen.

• Netwerk-/time-outproblemen tussen je server en Meshy die verkeerd worden geïnterpreteerd als een generatieprobleem.

Als een generatie niet aan je verwachtingen voldoet, of een verzoek helemaal mislukt, houd dan het volgende in gedachten:

• De Meshy API ondersteunt momenteel niet het opnieuw proberen van een bestaande taak op dezelfde plek — om het opnieuw te proberen, dien je een nieuw generatieverzoek in, dat normaal gesproken credits verbruikt.

• Voor tijdelijke netwerkfouten bij het aanroepen van de API (time-outs, 5xx-responses) is een korte exponentiële backoff voordat je het verzoek opnieuw indient redelijk.

• Voor polling zelf: probeer de "get task"-aanroep opnieuw bij tijdelijke netwerkfouten, maar beschouw één mislukte poll niet als een generatiefout — vertrouw alleen op het veld status zodra je een geslaagde response krijgt.

• Als je ingebouwde functionaliteit voor nieuwe pogingen voor generaties nodig hebt, neem dan contact op met het salesteam van Meshy over de opties voor enterprise-abonnementen.

Dit gebeurt bijna altijd omdat de code het resultaat probeert te lezen voordat de taak is voltooid. Controleer altijd of status SUCCEEDED is (en progress 100) voordat je model-URL's ophaalt.

Polling is eenvoudiger in te stellen en prima voor eenmalige scripts of scripts met een laag volume. Webhooks zijn beter voor productie-integraties met veel gelijktijdige taken, omdat ze onnodige herhaalde verzoeken voorkomen en je direct op de hoogte stellen wanneer een taak is voltooid.

Verwerk het idempotent — controleer de taak-id tegen wat je al hebt verwerkt, en sla herverwerking over als het al is afgehandeld.

Val terug op polling van de taak via id. Controleer ook of je endpoint publiek bereikbaar is via HTTPS en snel een 2xx-respons retourneert, omdat trage of onbereikbare endpoints problemen met de aflevering kunnen veroorzaken.

Momenteel niet — je moet een nieuwe generatieaanvraag indienen, die normaal credits verbruikt. Neem contact op met sales over enterprise-opties als je ingebouwde ondersteuning voor nieuwe pogingen nodig hebt.

Resultaatbestanden worden na voltooiing van een taak slechts een beperkte tijd op de servers van Meshy bewaard, dus download uitvoer naar je eigen opslag zodra de taak slaagt in plaats van te wachten.