lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

Webhooks

Fai in modo che Meshy invii una richiesta POST al tuo server quando un task API fa progressi o termina, così non devi fare polling.


Perché usare i webhook

I webhook richiedono meno lavoro e costano meno rispetto al polling dell'API per lo stato di ogni task. Meshy invia ogni aggiornamento non appena avviene, quindi lo ricevi prima, e i webhook scalano meglio del polling. Inoltre invii meno richieste, il che ti mantiene più lontano dai tuoi limiti di frequenza.


Configurare un webhook

Per aggiungere un webhook, segui questi passaggi:

  1. Apri la pagina Webhooks nella Developer Platform e fai clic su Create Webhook.
  2. In Payload URL, inserisci l'URL che riceve le consegne. Meshy effettua le consegne solo tramite https://.
  3. Conserva una copia del Webhook Secret che la finestra di dialogo compila automaticamente. Ogni consegna lo include, in modo che il tuo server possa verificare che una richiesta provenga da Meshy. Per un webhook che hai già creato, fai clic sull'icona a forma di occhio nella colonna Secret per visualizzarlo.
  4. Seleziona Active e fai clic su Confirm.

Ogni account può avere 5 webhook attivi e 10 in totale. Ogni webhook attivo riceve gli aggiornamenti di stato di tutti i tuoi task API.

Per testare un webhook con un server sul tuo computer, consulta Testare sul proprio computer.


Gestire una consegna

Per accettare una consegna, rispondi con uno stato inferiore a 400, come 200 o 202. Meshy attende circa 25 secondi per la risposta, quindi memorizza prima la consegna e rispondi subito dopo. Svolgi il lavoro più lento in seguito, ad esempio il download del modello.

Uno stato pari o superiore a 400, o l'assenza di risposta, viene considerato come una consegna fallita. Meshy la ripete con attese più lunghe tra un tentativo e l'altro, fino a 4 volte per un aggiornamento IN_PROGRESS e fino a 9 volte per uno stato finale. Se 20 aggiornamenti consecutivi falliscono a ogni tentativo, Meshy può disattivare il webhook. Per riattivarlo, modificalo nella pagina Webhooks e seleziona Active.

Scrivi il tuo codice tenendo conto di questi casi:

  • Le consegne possono arrivare fuori ordine. Una consegna IN_PROGRESS può arrivare dopo quella finale, quindi non lasciare che sostituisca uno stato finale.
  • Lo stesso aggiornamento può arrivare più di una volta. Gestisci ogni coppia di id e status una sola volta.
  • Chiunque conosca il tuo URL può inviargli una richiesta. Confronta X-MESHY-API-WEBHOOK-SECRET-KEY con la tua copia del secret e rifiuta una richiesta che non corrisponde.

Se la consegna finale di un task non è arrivata dopo circa il doppio del tempo tipico del task, recupera il task dal suo endpoint GET. Per i tempi tipici e quanto attendere, consulta Ciclo di vita del task.


Testare sul proprio computer

Meshy effettua consegne solo verso un URL pubblico https://, quindi non può raggiungere direttamente un server sul tuo computer. Per testare il codice sul tuo computer, inoltra un URL pubblico verso di esso con un proxy webhook. Questi passaggi usano smee.io, e qualsiasi servizio di proxy webhook funziona allo stesso modo.

  1. Apri smee.io e fai clic su Start a new channel. Copia l'URL sotto Webhook Proxy URL.

  2. Se non hai ancora il client smee, installalo:

    npm install --global smee-client
    
  3. Inoltra il canale al tuo server. Sostituisci WEBHOOK_PROXY_URL con il tuo URL proxy webhook:

    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
    

    L'output ha questo aspetto, dove WEBHOOK_PROXY_URL è il tuo URL proxy webhook:

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
    Connected WEBHOOK_PROXY_URL
    

    Lascialo in esecuzione durante il test. Per interrompere l'inoltro, premi Ctrl+C. Il tuo server riceve le consegne sulla porta 3000 al percorso /webhook, quindi configura il tuo codice per rimanere in ascolto lì.

  4. Nella pagina Webhooks, crea un webhook con l'URL proxy webhook come Payload URL.


Payload di consegna

Meshy invia una consegna mentre un task è IN_PROGRESS, e un'altra quando il task raggiunge uno stato finale. Un task può raggiungere il suo stato finale senza una consegna IN_PROGRESS.

Ogni consegna è una richiesta POST al tuo URL payload con questi header:

HeaderValore
X-MESHY-API-WEBHOOK-SECRET-KEYIl secret del webhook
X-MESHY-API-WEBHOOK-USER-IDL'ID dell'utente Meshy proprietario del webhook
Meshy-Webhook-Versionv1, il formato del corpo
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

Il corpo JSON è l'oggetto task. È lo stesso oggetto restituito dall'endpoint GET del task, ad eccezione di progress. Una consegna invia progress come uno di questi valori:

  • 50 mentre il task è IN_PROGRESS
  • 100 quando il task ha successo
  • 0 quando il task fallisce o viene annullato

Per i campi di ogni oggetto task, con un esempio, consulta le sezioni seguenti: