Meshy API Webhooks versus Polling: wanneer resultaten klaar zijn

Meshy API-generatietaken (Text to 3D, Image to 3D, Rigging en meer) lopen asynchroon — je dient een taak in en moet vervolgens uitzoeken wanneer deze klaar is voordat je het resultaat ophaalt. Dit artikel legt de levenscyclus van taken 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, geretourneerd in het veld status van het taakobject:

• PENDING — de taak staat in de wachtrij, maar de verwerking is nog niet gestart.

• IN_PROGRESS — de taak wordt momenteel verwerkt. Het veld progress (0-100) neemt toe naarmate het werk vordert.

• SUCCEEDED — de taak is succesvol voltooid en progress is 100. Resultaat-URL's (modellbestanden, texturen, previews) zijn nu beschikbaar in de response.

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

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

De belangrijkste regel bij het integreren 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 voor je taak-ID aanroept totdat deze een eindstatus 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 aan (bijvoorbeeld het Text to 3D- of Image to 3D task-by-id-endpoint) met tussenpozen — enkele seconden is gebruikelijk.

• Controleer het veld status bij elke response. Blijf pollen zolang deze PENDING of IN_PROGRESS is.

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

• Voeg een redelijke timeout/max-attements-bewaking toe aan je client, zodat een vastgelopen taak niet eeuwig blijft pollen.

Polling is eenvoudig en werkt goed voor scripts, batchtaken en integraties met een laag volume. Voor integraties met een hoog volume of gevoelig voor latentie is een webhook meestal een betere keuze.

In plaats van herhaaldelijk te vragen 'is het al klaar?', kun je Meshy vragen om je server op de hoogte te stellen zodra een taak is voltooid. Om webhooks te gebruiken:

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

• Zorg ervoor dat je endpoint publiek bereikbaar is via HTTPS en snel reageert (retourneer onmiddellijk een 2xx-status en verwerk de payload vervolgens asynchroon).

• Wanneer de taak een eindstatus bereikt, stuurt Meshy een payload naar je endpoint met daarin de taak-id en de uiteindelijke status.

• Zoek bij ontvangst de volledige taakdetails op via de id via de API in plaats van alleen de webhook-body te vertrouwen, zodat je zeker weet dat je het gezaghebbende, actuele resultaat hebt.

Webhooks verminderen onnodige API-aanroepen en geven je vrijwel directe meldingen, maar je moet toch een periodieke polling-fallback aanhouden voor taken waarbij een webhooklevering mogelijk gemist of vertraagd kan worden (bijv. door een tijdelijk netwerkprobleem aan jouw kant).

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 geleverd voor dezelfde taak (retries aan de afzenderkant, netwerkduplicatie, enz.).

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

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

Een response met "status": "SUCCEEDED" en "progress": 100 is het enige signaal dat garandeert dat de resultaat-payload (model-URL's, texturen, miniaturen) volledig is en veilig te gebruiken. Concreet, in je code:

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

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

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

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

• Te vroeg ophalen. De resultaat-URL aanroepen of de modellvelden lezen voordat status SUCCEEDED is. Dit is verreweg de meest frequente oorzaak.

• Verlopen assets. Te lang wachten na SUCCEEDED met downloaden — resultaat-URL's stoppen met werken nadat de bewaartermijn voor dat taaktype is verstreken.

• Een verouderde of verkeerde taak-ID gebruiken — bijvoorbeeld het hergebruiken van een ID van een eerder, ongerelateerd verzoek.

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

• Netwerk-/timeoutproblemen tussen je server en Meshy die worden aangezien voor een generatieprobleem.

Als een generatie niet aan je verwachtingen voldoet, of een verzoek volledig 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, wat normaal gesproken credits verbruikt.

• Bij tijdelijke netwerkfouten bij het aanroepen van de API (timeouts, 5xx-responses) is een korte exponentiële backoff vóór het opnieuw indienen van het verzoek redelijk.

• Voor polling zelf: probeer de 'get task'-aanroep opnieuw bij tijdelijke netwerkfouten, maar behandel één mislukte poll niet als een generatiefout — vertrouw het veld status alleen nadat je een succesvolle response hebt ontvangen.

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

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

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

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

Val terug op het direct pollen van de taak via de id. Controleer ook of je endpoint publiek bereikbaar is via HTTPS en snel een 2xx-response retourneert, aangezien trage of onbereikbare endpoints leveringsproblemen kunnen veroorzaken.

Momenteel niet — je moet een nieuw generatieverzoek indienen, wat normaal gesproken credits verbruikt. Neem contact op met sales over enterprise-opties als je ingebouwde retry-ondersteuning nodig hebt.

Resultaatbestanden worden slechts beperkte tijd bewaard op de servers van Meshy nadat een taak is voltooid, dus download de resultaten naar je eigen opslag zodra de taak slaagt in plaats van te wachten.

• Waarom kom ik consequent fouten tegen bij het ophalen van de modellen uit een generatieresultaat via de API?