Meshy API Webhook vs Polling: quando i risultati sono pronti

I task di generazione dell'API Meshy (Text to 3D, Image to 3D, Rigging e altri) vengono eseguiti in modo asincrono: invii un task e poi devi scoprire quando è completato prima di recuperare il risultato. Questo articolo spiega il ciclo di vita del task e i due modi supportati per sapere quando un task è terminato: polling e webhook — oltre a come evitare il problema più comune, ovvero gli "errori nel recupero del modello".

Ogni task di generazione passa attraverso un piccolo insieme di stati, restituiti nel campo status dell'oggetto task:

• PENDING — il task è in coda ma l'elaborazione non è ancora iniziata.

• IN_PROGRESS — il task è in fase di elaborazione attiva. Il campo progress (0-100) aumenta man mano che il lavoro avanza.

• SUCCEEDED — il task è terminato con successo e progress è 100. Gli URL dei risultati (file del modello, texture, anteprime) sono ora disponibili nella risposta.

• FAILED — il task non è potuto andare a completamento. I crediti per i task non riusciti vengono rimborsati automaticamente.

• CANCELED — il task è stato annullato prima del completamento.

La regola più importante quando ci si integra con l'API: non provare mai a recuperare o utilizzare gli URL dei risultati finché lo status del task non è SUCCEEDED. Leggere i risultati mentre un task è ancora PENDING o IN_PROGRESS è la causa più frequente delle segnalazioni di "errori nel recupero del modello".

Il polling consiste nel chiamare ripetutamente l'endpoint "get task" per il tuo task ID finché non raggiunge uno stato terminale (SUCCEEDED, FAILED o CANCELED). Un semplice ciclo di polling appare così:

• Invia la richiesta di generazione e memorizza il task id restituito.

• Chiama l'endpoint "retrieve task" corrispondente (ad esempio, l'endpoint task-by-id di Text to 3D o Image to 3D) a intervalli regolari — tipicamente ogni pochi secondi.

• Controlla il campo status in ogni risposta. Continua il polling finché è PENDING o IN_PROGRESS.

• Interrompi il polling non appena status è SUCCEEDED (leggi gli URL dei risultati), FAILED o CANCELED.

• Aggiungi un guardia ragionevole di timeout/numero massimo di tentativi nel tuo client, in modo che un task bloccato non venga interrogato all'infinito.

Il polling è semplice e funziona bene per script, job batch e integrazioni a basso volume. Per integrazioni ad alto volume o sensibili alla latenza, un webhook è di solito una scelta migliore.

Invece di chiedere ripetutamente "è finito?", puoi chiedere a Meshy di notificare al tuo server il momento in cui un task si conclude. Per usare i webhook:

• Configura un URL webhook (callback) raggiungibile da Meshy — in genere viene impostato a livello di impostazioni account/API oppure passato come parametro nella richiesta di generazione, a seconda dell'endpoint.

• Assicurati che il tuo endpoint sia pubblicamente raggiungibile via HTTPS e risponda rapidamente (restituisci immediatamente uno stato 2xx, poi elabora il payload in modo asincrono).

• Quando il task raggiunge uno stato terminale, Meshy invia un payload al tuo endpoint contenente il task id e il suo status finale.

• Alla ricezione, recupera i dettagli completi del task tramite id usando l'API invece di fidarti solo del corpo del webhook, per assicurarti di avere il risultato autorevole e aggiornato.

I webhook riducono le chiamate API non necessarie e ti offrono una notifica quasi istantanea, ma dovresti comunque mantenere un fallback di polling periodico per i task in cui la consegna del webhook potrebbe andare persa o subire ritardi (ad esempio a causa di un problema di rete temporaneo da parte tua).

Che tu usi il polling o i webhook, il tuo codice di gestione dei risultati dovrebbe essere idempotente — cioè eseguibile più volte in sicurezza per lo stesso task senza effetti collaterali. Questo è importante perché:

• Un webhook può essere consegnato più di una volta per lo stesso task (retry lato mittente, duplicazioni di rete, ecc.).

• Un ciclo di polling e un gestore di webhook potrebbero entrambi tentare di elaborare lo stesso task completato se entrambi sono attivi.

Per rimanere idempotente, basa la tua logica di elaborazione sul task id — ad esempio, controlla se hai già memorizzato/scaricato i risultati per quel id prima di farlo di nuovo, e rendi "contrassegna come elaborato" un singolo passaggio atomico nel tuo database.

Una risposta con "status": "SUCCEEDED" e "progress": 100 è l'unico segnale che garantisce che il payload del risultato (URL del modello, texture, miniature) sia completo e sicuro da usare. Concretamente, nel tuo codice:

• Verifica status === "SUCCEEDED" prima di leggere qualsiasi cosa dai campi result/URL del modello.

• Non fare affidamento solo su progress — controlla sempre anche status, poiché il progresso può mostrare brevemente valori alti prima che il task sia completamente finalizzato.

• Scarica i file dei risultati prontamente una volta raggiunto SUCCEEDED — gli asset generati vengono conservati sui server di Meshy solo per un tempo limitato, dopo il quale gli URL non saranno più risolvibili.

La maggior parte delle segnalazioni del tipo "non riesco a recuperare il mio modello" riconduce a una di queste cause:

• Recupero troppo anticipato. Chiamare l'URL del risultato, o leggere i campi del modello, prima che status sia SUCCEEDED. È di gran lunga la causa più frequente.

• Asset scaduti. Avere atteso troppo dopo SUCCEEDED prima di scaricare — gli URL dei risultati smettono di funzionare dopo la finestra di conservazione prevista per quel tipo di task.

• Uso di un task ID obsoleto o errato — ad esempio, riutilizzare un ID di una richiesta precedente e non correlata.

• Trattare FAILED come uno stato transitorio e continuare a interrogare un task già fallito invece di reinviarlo.

• Problemi di rete/timeout tra il tuo server e Meshy scambiati per un problema di generazione.

Se una generazione non soddisfa le tue aspettative, o una richiesta fallisce del tutto, tieni presente quanto segue:

• L'API Meshy non supporta attualmente il retry di un task esistente in loco — per riprovare, invia una nuova richiesta di generazione, che consumerà i crediti normalmente.

• Per guasti di rete temporanei durante la chiamata all'API (timeout, risposte 5xx), un breve exponential backoff prima di reinviare la richiesta è ragionevole.

• Per il polling stesso, riprova la chiamata "get task" in caso di errori di rete temporanei, ma non considerare un singolo poll fallito come un fallimento della generazione — fida solo del campo status una volta ricevuta una risposta andata a buon fine.

• Se ti serve una funzionalità di retry integrata per le generazioni, contatta il team di vendita di Meshy per informazioni sulle opzioni del piano enterprise.

Questo accade quasi sempre perché il codice tenta di leggere il risultato prima che il task sia terminato. Verifica sempre che status sia SUCCEEDED (e progress sia 100) prima di recuperare gli URL del modello.

Il polling è più semplice da configurare e va bene per script a basso volume o occasionali. I webhook sono migliori per le integrazioni di produzione con molti task concorrenti, poiché evitano richieste ripetute non necessarie e ti notificano immediatamente quando un task si completa.

Gestiscilo in modo idempotente — controlla il task id rispetto a ciò che hai già elaborato e salta la rielaborazione se è già stato gestito.

Ripiega sul polling del task tramite id direttamente. Verifica inoltre che il tuo endpoint sia pubblicamente raggiungibile via HTTPS e restituisca rapidamente una risposta 2xx, poiché endpoint lenti o irraggiungibili possono causare problemi di consegna.

Non attualmente — dovrai inviare una nuova richiesta di generazione, che consuma i crediti normalmente. Contatta il reparto vendite per le opzioni enterprise se ti serve il supporto per il retry integrato.

I file dei risultati vengono conservati sui server di Meshy solo per un tempo limitato dopo il completamento di un task, quindi scarica gli output nel tuo storage non appena il task ha successo invece di attendere.

• Perché incontro costantemente errori nel recuperare i modelli dal risultato di una generazione usando l'API?