Webhook e polling dell'API Meshy: quando i risultati sono pronti

Le attività di generazione dell'API Meshy (Text to 3D, Image to 3D, Rigging e altro) vengono eseguite in modo asincrono: invii un'attività e poi devi scoprire quando è terminata prima di recuperare il risultato. Questo articolo spiega il ciclo di vita dell'attività e i due modi supportati per sapere quando un'attività è terminata: polling e webhook, oltre a come evitare il problema più comune di "errori durante il recupero del modello".

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

• PENDING — l'attività è stata messa in coda ma l'elaborazione non è ancora iniziata.

• IN_PROGRESS — l'attività è in fase di elaborazione attiva. Il campo progress (0-100) aumenta man mano che il lavoro viene completato.

• SUCCEEDED — l'attività è terminata correttamente e progress è 100. Gli URL dei risultati (file del modello, texture, anteprime) sono ora disponibili nella risposta.

• FAILED — l'attività non è riuscita a completarsi. I crediti per le attività non riuscite vengono rimborsati automaticamente.

• CANCELED — l'attività è stata annullata prima del completamento.

La regola più importante in assoluto quando si integra l'API: non tentare mai di recuperare o utilizzare gli URL dei risultati finché il status dell'attività non è SUCCEEDED. Leggere i risultati mentre un'attività è ancora PENDING o IN_PROGRESS è la causa più comune delle segnalazioni di "errori durante il recupero del modello".

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

• Invia la richiesta di generazione e memorizza l'id dell'attività 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: qualche secondo è tipico.

• 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 nel tuo client un timeout o un limite massimo di tentativi ragionevole, così un'attività bloccata non esegue il polling all'infinito.

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

Invece di chiedere ripetutamente "è finito?", puoi chiedere a Meshy di notificare al tuo server il momento in cui un'attività termina. Per usare i webhook:

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

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

• Quando l'attività raggiunge uno stato terminale, Meshy invia un payload al tuo endpoint contenente l'id dell'attività e il suo status finale.

• Al ricevimento, recupera i dettagli completi dell'attività tramite l'id usando l'API invece di fidarti solo del corpo del webhook, per essere sicuro di avere il risultato autorevole e aggiornato.

I webhook riducono le chiamate API non necessarie e forniscono una notifica quasi immediata, ma dovresti comunque mantenere un fallback di polling periodico per le attività in cui una consegna del webhook potrebbe essere persa o ritardata (ad esempio a causa di un problema di rete temporaneo dalla tua parte).

Che tu utilizzi il polling o i webhook, il codice che gestisce i risultati deve essere idempotente, ovvero sicuro da eseguire più di una volta per la stessa attività senza effetti collaterali. Questo è importante perché:

• Un webhook può essere consegnato più di una volta per la stessa attività (nuovi tentativi da parte del mittente, duplicazioni di rete, ecc.).

• Un ciclo di polling e un gestore di webhook potrebbero entrambi tentare di elaborare la stessa attività completata se sono in esecuzione contemporaneamente.

Per rimanere idempotente, basare la logica di elaborazione sull'id dell'attività — ad esempio, verificare se hai già archiviato/scaricato i risultati per quell'id prima di farlo di nuovo, e rendere "segna 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 dei modelli, texture, anteprime) sia completo e utilizzabile in sicurezza. Concretamente, nel tuo codice:

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

• Non basarti solo su progress — controlla sempre anche status, poiché progress può mostrare brevemente valori elevati prima che l'attività sia completamente finalizzata.

• Scarica tempestivamente i file del risultato una volta ottenuto SUCCEEDED — gli asset generati vengono conservati sui server di Meshy solo per un periodo limitato, dopodiché gli URL non saranno più risolvibili.

La maggior parte delle segnalazioni "non riesco a recuperare il mio modello" risale 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. Attendere troppo tempo dopo SUCCEEDED per scaricare: gli URL dei risultati smettono di funzionare una volta trascorsa la finestra di conservazione per quel tipo di attività.

• Uso di un ID attività obsoleto o errato, ad esempio riutilizzando un ID di una richiesta precedente e non correlata.

• Trattare FAILED come uno stato transitorio e continuare a interrogare un'attività già fallita invece di inviarla di nuovo.

• Problemi di rete o di timeout tra il tuo server e Meshy interpretati erroneamente come 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 al momento non supporta il nuovo tentativo di un'attività esistente sul posto: per riprovare, invia una nuova richiesta di generazione, che consumerà crediti come di consueto.

• Per gli errori di rete temporanei quando chiami l'API (timeout, risposte 5xx), un breve backoff esponenziale 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 polling non riuscito come un fallimento della generazione: fidati del campo status solo dopo aver ottenuto una risposta riuscita.

• Se hai bisogno di funzionalità di nuovo tentativo integrate per le generazioni, contatta il team commerciale di Meshy per le opzioni del piano enterprise.

Ciò accade quasi sempre perché il codice sta tentando di leggere il risultato prima che l'attività sia terminata. Verifica sempre che status sia SUCCEEDED (e che progress sia 100) prima di recuperare gli URL dei modelli.

Il polling è più semplice da configurare e va bene per script occasionali o a basso volume. I webhook sono preferibili per integrazioni in produzione con molte attività concorrenti, poiché evitano richieste ripetute non necessarie e ti notificano immediatamente quando un'attività viene completata.

Deve gestirlo in modo idempotente: confronta l'id dell'attività con quelli già elaborati e salta la rielaborazione se è già stato gestito.

Passa al polling dell'attività tramite id direttamente. Verifica inoltre che il tuo endpoint sia raggiungibile pubblicamente tramite HTTPS e restituisca rapidamente una risposta 2xx, poiché endpoint lenti o irraggiungibili possono causare problemi di consegna.

Al momento no: devi inviare una nuova richiesta di generazione, che consuma crediti normalmente. Contatta il reparto commerciale per le opzioni enterprise se hai bisogno di un supporto integrato per i nuovi tentativi.

I file dei risultati vengono conservati sui server di Meshy solo per un periodo limitato dopo il completamento di un'attività, quindi scarica gli output sul tuo storage non appena l'attività è completata, anziché aspettare.